Todo Txt

PyPI version Python 3.10+ License: MIT

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.