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

1. Clone this repository:

   git clone https://github.com/danjdewhurst/todo-md-mcp.git

   cd todo-md-mcp

   

   npm install

   

   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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. 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.