todo-txt-mcp

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