home / mcp / todo markdown mcp server

Todo Markdown MCP Server

A basic todo MCP server powered by Markdown

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "danjdewhurst-todo-md-mcp": {
      "command": "node",
      "args": [
        "/path/to/todo-md-mcp/dist/index.js"
      ],
      "env": {
        "TODO_FILE_PATH": "/Users/yourname/Documents/todo.md"
      }
    }
  }
}

This MCP server lets you manage a todo list through a standardized Model Context Protocol interface, storing tasks in a lightweight markdown file. It supports full CRUD operations and assigns persistent IDs to each item, making it easy for AI assistants to create, read, update, and delete tasks in a predictable, human-readable format.

How to use

You will interact with the server through an MCP client to manage your todos. Use the available tools to list all tasks, add new items, update existing ones, delete items, and clear completed tasks. All operations are designed to work with a markdown-backed file in a way that keeps your data portable and easy to inspect.

Typical workflows include creating a new task with a descriptive text, marking tasks as completed as you finish them, and periodically removing completed items to keep the list focused. Each todo item carries a unique ID that remains stable across updates, ensuring you can reference and modify the exact item you intend.

How to install

Prerequisites you need before installing: Node.js 18 or higher and an MCP-compatible client.

Install the MCP server globally so you can run it from anywhere:

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

Alternatively, you can run the MCP server locally from your project after cloning the source and installing dependencies. If you are using a development setup, follow these steps:

git clone https://github.com/danjdewhurst/todo-md-mcp.git
cd todo-md-mcp
npm install
npm run build

To start the server in development mode, you can run the built entry point directly with Node, or use the package manager’s runner. The server exposes the standard MCP commands you will invoke from your MCP client.

node /path/to/todo-md-mcp/dist/index.js

If you prefer running via npx (globally installed or from the npm registry), use the following startup command:

npx @danjdewhurst/todo-md-mcp

Configuration and runtime details

By default, the server stores todos in a file named todo.md in the current working directory. If you need to place the file elsewhere, configure the environment variable TODO_FILE_PATH with the full path to your markdown file. This is especially helpful when the server runs in environments with restricted write access.

Example configurations for running via Claude Desktop or similar MCP clients show two alternative startup forms: one using a direct node invocation to a built dist file, and another using npx to run the package.

Configure the file location when launching through an MCP client by setting the environment variable in the server configuration.

File format and data model

Todos are stored in a Markdown file named todo.md in the project root. Each item uses standard markdown checkboxes and includes a hidden ID as an HTML comment for tracking. A sample structure looks like this:

# 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 -->

Development and testing

The project includes a complete test suite that covers parsing and generation of the markdown, CRUD operations, error handling, and file management.

Run the tests locally to verify behavior after changes.

npm test

Notes and tips

Make sure the target directory for the TODO_FILE_PATH exists and that you have write permissions to it. When integrating with environments like Claude Desktop, placing the file in a user-writable directory (for example ~/Documents or ~/Desktop) is recommended.

MCP Tooling and endpoints

This server provides a set of MCP tools to interact with your markdown-backed todo list. You can list, add, update, delete, and clear completed items using the tools exposed by the server.

Available tools

list_todos

Lists all todo items from the markdown file and provides a summary of counts and statuses.

add_todo

Adds a new todo item with provided text and assigns a persistent ID.

update_todo

Updates an existing todo's text or completion status by its ID.

delete_todo

Removes a todo item by its ID and returns a success confirmation.

clear_completed

Removes all items marked as completed and returns the number of items cleared.