About Todo.txt MCP Server
Todo.txt MCP Server connects plain-text todo.txt files to AI assistants such as Claude. It provides task management tools while retaining compatibility with the todo.txt format.
Key features
- 01List and filter tasks
- 02Create, update, and delete tasks
- 03Complete tasks
- 04Search by text
- 05Filter by priority, project, or context
- 06View task statistics
Use cases
- 01Manage a todo.txt list with an AI assistant
- 02Find tasks by project or context
- 03Update task status and details
- 04Review task counts
MCP support
The MCP server exposes tools for listing, creating, completing, updating, deleting, searching, and filtering todos, as well as viewing statistics.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project READMETodo.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.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.