Todo MD MCP
@danjdewhurst
An MCP (Model Context Protocol) server that provides todo list functionality backed by a simple markdown file. This server allows AI assistants to manage todo items in a standardized markdown format.
Overview
What is Todo MD MCP?
An MCP server that provides todo list functionality backed by a simple markdown file. It enables AI assistants to create, read, update, and delete todo items using standard checkbox syntax in a .md file.
How to use Todo MD MCP?
Install globally via npm install -g @danjdewhurst/todo-md-mcp or clone and build locally. Add the server to an MCP client (e.g., Claude Desktop) using the npx command or path to the built file. Optionally set the TODO_FILE_PATH environment variable to specify where the todo.md file is stored. The server exposes five tools: list_todos, add_todo, update_todo, delete_todo, and clear_completed.
Key features of Todo MD MCP
- Markdown-based storage using standard checkbox syntax
- Full CRUD operations for todo items
- Persistent unique IDs for reliable updates
- MCP compliant server implementation
- Fully typed TypeScript with error handling
- Complete test suite with Vitest
Use cases of Todo MD MCP
- AI assistant managing a user’s personal todo list via chat
- Integrating task management into Claude Desktop workflows
- Maintaining a simple project todo list in markdown format
- Automating task tracking through MCP tools
- Clearing completed items to keep the list tidy
FAQ from Todo MD MCP
How do I install the server?
Install globally: npm install -g @danjdewhurst/todo-md-mcp. For local development, clone the repository, install dependencies, and build with npm run build.
How do I configure the todo file location?
Set the TODO_FILE_PATH environment variable in your MCP client configuration. For example: "env": { "TODO_FILE_PATH": "/Users/yourname/Documents/todo.md" }. Ensure the directory exists and you have write permissions.
What is the format of the todo markdown file?
Each todo uses standard markdown checkbox syntax (- [ ] or - [x]) followed by a hidden HTML comment containing a unique ID. The file also has a header (# Todo List) and a footer comment.
What are the available tools?
list_todos (list all items), add_todo (create a new item), update_todo (modify text or completion status), delete_todo (remove an item by ID), and clear_completed (remove all completed items).
What are the system requirements?
Node.js 18 or higher and an MCP-compatible client
