Todo Markdown MCP Server
Stores and manages todo items in a standard markdown file format with checkbox syntax, maintaining persistent IDs for each task
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Todo Markdown MCP Server add a todo to buy groceries tomorrow"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Todo Markdown MCP Server
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.
Features
Markdown-based storage: Todos are stored in a simple
todo.mdfile using standard checkbox syntaxFull CRUD operations: Create, read, update, and delete todo items
Persistent IDs: Each todo has a unique identifier for reliable updates
MCP compliance: Follows the Model Context Protocol specification
TypeScript: Fully typed implementation with comprehensive error handling
Testing: Complete test suite with Vitest
Related MCP server: Todo MCP Server
Installation
From NPM
npm install -g @danjdewhurst/todo-md-mcpLocal Development
Clone this repository:
git clone https://github.com/danjdewhurst/todo-md-mcp.git cd todo-md-mcpInstall dependencies:
npm installBuild the project:
npm run build
Usage
With Claude Desktop
Add this server to your Claude Desktop configuration:
{
"mcpServers": {
"todo-md": {
"command": "node",
"args": ["/path/to/todo-md-mcp/dist/index.js"]
}
}
}Or if installed globally via NPM:
{
"mcpServers": {
"todo-md": {
"command": "npx",
"args": ["@danjdewhurst/todo-md-mcp"]
}
}
}Configuring Todo File Location
By default, the server creates a todo.md file in the current working directory. When using Claude Desktop, this might be a system directory where you don't have write permissions. To specify a custom location for your todo file, use the TODO_FILE_PATH environment variable:
{
"mcpServers": {
"todo-md": {
"command": "npx",
"args": ["@danjdewhurst/todo-md-mcp"],
"env": {
"TODO_FILE_PATH": "/Users/yourname/Documents/todo.md"
}
}
}
}This solves the common "read-only file system" error by ensuring the todo file is created in a location where you have write permissions.
Recommended locations:
~/Documents/todo.md- Your Documents folder~/Desktop/todo.md- Your Desktop/path/to/your/project/todo.md- Within a specific project
Important: Make sure the directory exists and you have write permissions to the specified location.
Available Tools
The server provides the following MCP tools:
list_todos
Lists all todo items from the markdown file.
Parameters: None
Returns: JSON object with todos array and summary statistics
add_todo
Adds a new todo item.
Parameters:
text(string, required): The todo item text
Returns: The created todo item with generated ID
update_todo
Updates an existing todo item.
Parameters:
id(string, required): The todo item IDtext(string, optional): New text for the todocompleted(boolean, optional): Mark as completed/incomplete
Returns: The updated todo item
delete_todo
Deletes a todo item.
Parameters:
id(string, required): The todo item ID to delete
Returns: Success confirmation
clear_completed
Removes all completed todo items.
Parameters: None
Returns: Number of items cleared
File Format
The server manages a todo.md file in your project root with the following format:
# Todo List
- [ ] First incomplete task <!-- id:550e8400-e29b-41d4-a716-446655440000 -->
- [x] Completed task <!-- id:6ba7b810-9dad-11d1-80b4-00c04fd430c8 -->
- [ ] Another task <!-- id:6ba7b811-9dad-11d1-80b4-00c04fd430c8 -->
<!-- Generated by MCP Todo Server -->Each todo item includes:
Standard markdown checkbox syntax (
- [ ]or- [x])The todo text
A hidden HTML comment with a unique ID for tracking
Development
Scripts
npm run build- Build the TypeScript projectnpm run dev- Build and run the servernpm run watch- Watch for changes and rebuildnpm test- Run the test suitenpm run test:watch- Run tests in watch modenpm run lint- Run ESLintnpm run format- Format code with Prettier
Testing
The project includes comprehensive tests covering all functionality:
npm testTests cover:
Markdown parsing and generation
CRUD operations
Error handling
File management
Project Structure
todo-md-mcp/
├── src/
│ ├── index.ts # Main MCP server implementation
│ ├── todoManager.ts # Todo CRUD operations and markdown parsing
│ └── types.ts # TypeScript type definitions
├── tests/
│ └── todoManager.test.ts # Test suite
├── dist/ # Built JavaScript files
├── package.json
├── tsconfig.json
├── .eslintrc.json
├── .prettierrc
├── vitest.config.ts
└── README.mdRequirements
Node.js 18 or higher
An MCP-compatible client (like Claude Desktop)
License
MIT
Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
Submit a pull request
Model Context Protocol
This server implements the Model Context Protocol (MCP), an open protocol that standardizes how applications provide context to Large Language Models. MCP enables secure, controlled access to local and remote resources.
For more information about MCP, visit the official documentation.
Available Tools
5 toolsadd_todoC
Add a new todo item
Inputs: text (required).
clear_completedB
Remove all completed todo items
Inputs: no named parameters.
delete_todoC
Delete a todo item
Inputs: id (required).
list_todosB
List all todos from the markdown file
Inputs: no named parameters.
update_todoC
Update an existing todo item
Inputs: id (required), text, completed.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: add, clear completed, delete, list, and update todos. There is no overlap in functionality, and an agent can easily distinguish between them based on their specific actions.
All tool names follow a consistent verb_noun pattern (e.g., add_todo, delete_todo). The naming is uniform throughout, using snake_case and clear verbs that accurately describe each action.
With 5 tools, this server is well-scoped for managing todos in a markdown file. Each tool serves a distinct and necessary function, covering core operations without being overly simplistic or bloated.
The tool set provides complete CRUD coverage for todo management: create (add_todo), read (list_todos), update (update_todo), and delete (delete_todo), plus a utility for clearing completed items. There are no obvious gaps for the intended domain.
Maintenance
Related MCP Connectors
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
ADHD-friendly task management MCP server for ChaTodo: organize tasks, lists, and priorities.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server that exposes a TODO list API to AI assistants, enabling natural language management of tasks with create, read, update, and delete operations.-
- AlicenseNot gradedqualityDmaintenanceA small MCP server for managing todos, enabling assistants like Claude to create, update, and query task lists through natural conversation. Stores everything in a local SQLite database.13 npm1ISC
- AlicenseAqualityDmaintenanceA small Model Context Protocol (MCP) server that lets an AI assistant manage a to-do list on your behalf.4MIT
- AlicenseBqualityCmaintenanceA basic MCP server for managing a todo list stored in a local JSON file, enabling task creation, completion, listing, and daily summary generation.26 npmMIT