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.md file using standard checkbox syntax
Full 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

Installation

From NPM

npm install -g @danjdewhurst/todo-md-mcp

Local Development

Clone this repository:
git clone https://github.com/danjdewhurst/todo-md-mcp.git cd todo-md-mcp
Install dependencies:
npm install
Build 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 ID
text (string, optional): New text for the todo
completed (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 project
npm run dev - Build and run the server
npm run watch - Watch for changes and rebuild
npm test - Run the test suite
npm run test:watch - Run tests in watch mode
npm run lint - Run ESLint
npm run format - Format code with Prettier

Testing

The project includes comprehensive tests covering all functionality:

npm test

Tests 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.md

Requirements

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.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

An MCP server that allows AI assistants to manage todo lists stored in a simple markdown file, supporting creation, reading, updating, and deletion of todo items with persistent IDs.

Related MCP Servers

Todo List MCP Server
RegiByte
A
security
A
license
A
quality
A Model Context Protocol (MCP) server that provides tools for managing todo items, including creation, updating, completion, deletion, searching, and summarizing tasks.
Last updated -
10
22
TypeScript
MIT License
Coding Todo Server
dennismartis
-
security
F
license
-
quality
An MCP server that provides tools and resources for managing a coding project's todo list, allowing users to view, add, update, and delete todo items with details like priority, status, and tags.
Last updated -
1
Python
Todoist MCP
Doist
A
security
A
license
A
quality
An MCP server that enables LLMs to interact with Todoist tasks, projects, and other features through the Todoist API.
Last updated -
36
653
131
TypeScript
MIT License
Linear MCP Server
argia-andreas
-
security
F
license
-
quality
A server that allows AI assistants to access and retrieve Linear ticket data through the Model Context Protocol (MCP) standard, currently focused on fetching a user's todo tickets.
Last updated -
685
TypeScript

View all related MCP servers

Todo Markdown MCP Server