Todo.txt MCP Server

A Model Context Protocol server that connects todo.txt files to AI assistants like Claude. Manage your tasks through natural language while keeping the simplicity and portability of plain text.

Installation

# Recommended
uv tool install todo-txt-mcp

# Or run directly without installing
uvx todo-txt-mcp

# Alternatives
pipx install todo-txt-mcp
pip install todo-txt-mcp

Configuration

Add to your Claude Desktop config:

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"
            ]
        }
    }
}

Restart Claude Desktop. The tools icon confirms the server is connected.

Custom todo.txt location

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

todo.sh integration

If you use todo.sh, the server automatically detects your config from ~/.todo/config, ~/.todo.cfg, or standard system locations.

Environment variables

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

Available Tools

| Tool | Description | |----------------------|----------------------------------| | list_todos | List todos with optional filters | | add_todo | Create new todos | | complete_todo | Mark todos as completed | | update_todo | Modify existing todos | | delete_todo | Remove todos | | search_todos | Find todos by text | | filter_by_priority | Filter by priority (A-Z) | | filter_by_project | Filter by project (+tag) | | filter_by_context | Filter by context (@tag) | | get_statistics | Get todo statistics |

Todo.txt Format

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

Contributing

See CONTRIBUTING.md for guidelines. Bug reports and feature requests welcome via GitHub Issues.

License

MIT - see LICENSE.