What is Todo Txt Mcp

todo-txt-mcp is a Model Context Protocol server that connects your todo.txt files to AI assistants like Claude Desktop, allowing you to manage your todo list using natural language while retaining the simplicity of the todo.txt format.

Use cases

Use cases include managing personal to-do lists, collaborating on team projects, integrating with AI assistants for enhanced productivity, and utilizing statistics for performance tracking.

How to use

To use todo-txt-mcp, install it using commands like ‘uvx todo-txt-mcp’ for a quick test or ‘uv tool install todo-txt-mcp’ for a global installation. Configure it in Claude Desktop by adding it to the configuration file, and then restart Claude Desktop to start using it.

Key features

Key features include a natural language interface for managing todos, full CRUD operations, smart filtering by text, priority, projects, and contexts, productivity statistics and insights, todo.sh integration, file safety with automatic backups, and modern installation options.

Where to use

todo-txt-mcp can be used in personal productivity management, project management, and any scenario where task organization and AI assistance are beneficial.

Todo.txt MCP Server

A powerful Model Context Protocol (MCP) server that connects your todo.txt files to AI assistants like Claude Desktop. Manage your todo list through natural language while maintaining the simplicity and portability of the todo.txt format.

✨ Features

• 🔍 Natural Language Interface: Ask AI to find, create, and manage your todos
• 📝 Full CRUD Operations: Create, read, update, and delete todos with AI assistance
• 🎯 Smart Filtering: Search by text, priority, projects (+project), or contexts (@context)
• 📊 Statistics & Insights: Get comprehensive stats about your productivity
• 🔄 todo.sh Integration: Automatically works with existing todo.sh setups
• 💾 File Safety: Automatic backups and configurable safety limits
• ⚡ Modern Installation: Install with uvx, uv, pipx, or pip

🚀 Quick Start

1. Install

# Quick test (no installation required)
uvx todo-txt-mcp

# Install globally (recommended)
uv tool install todo-txt-mcp

# Using pipx (isolated environment)
pipx install todo-txt-mcp

# Using pip (traditional)
pip install todo-txt-mcp

2. Configure Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "todo-txt": {
      "command": "uvx",
      "args": [
        "todo-txt-mcp"
      ]
    }
  }
}

3. Restart Claude Desktop

Look for the 🔨 tools icon to confirm the server is connected.

💬 Example Conversations

Once configured, you can interact with your todos naturally:

You: “Add a todo to call mom tomorrow with high priority”

You: “Show me all my work-related todos”

You: “What’s my most important task right now?”

You: “Mark the grocery shopping task as completed”

You: “How many todos do I have in my @phone context?”

🛠️ Available Tools

The server provides these MCP tools for AI interaction:

📄 Todo.txt Format Support

Fully compatible with the todo.txt specification:

(A) Call Mom +family @phone
x 2025-05-31 2025-05-30 (B) Buy groceries +shopping @errands
Write project proposal +work @computer
(C) Schedule dentist appointment +health @phone

⚙️ Configuration

Works with Existing todo.sh Setup

If you’re already using todo.sh, the server automatically detects your configuration:

• ~/.todo/config
• ~/.todo.cfg
• /etc/todo/config
• /usr/local/etc/todo/config

Custom Configuration

Specify a custom todo.txt file:

{
  "mcpServers": {
    "todo-txt": {
      "command": "uvx",
      "args": [
        "todo-txt-mcp",
        "/path/to/your/todo.txt"
      ]
    }
  }
}

Environment Variables

Configure via environment variables:

TODO_MCP_TODO_FILE_PATH=/path/to/todo.txt
TODO_MCP_BACKUP_ENABLED=true
TODO_MCP_MAX_FILE_SIZE=10000000

🔒 Security & Privacy

• Local only: All processing happens on your machine
• No network requests: Your todos never leave your device
• File safety: Automatic backups and size limits
• Sandboxed: Only accesses configured todo.txt files

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

• Bug reports: Use the issue template
• Feature requests: Use the feature template
• Questions: Start a GitHub Discussion

📋 Roadmap

• [ ] Due date support and reminders
• [ ] Recurring todos
• [ ] Multiple file support
• [ ] Sync capabilities
• [ ] Advanced search with regex
• [ ] Bulk operations

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with the Model Context Protocol
• Follows the todo.txt format specification
• Inspired by the todo.sh command-line tool
• Powered by pytodotxt for parsing