home / mcp / todo mcp server

Todo MCP Server

learning to build and interact with MCPs

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "calamityadam-mcp-todo": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "MCP_STDIO": "1",
        "TODO_MCP_TOKEN": "YOUR_TOKEN_IF_SET"
      }
    }
  }
}

A todo list MCP server lets you manage tasks from both a local stdio client and a streamable HTTP interface. It stores todos persistently and provides a simple set of operations you can perform from your MCP clients, making it easy to integrate into your apps or development workflow.

How to use

Choose your transport and connect your client to manage your todos. If you prefer a local, in-process integration, run the stdio transport and start the server with the appropriate environment flag. If you want remote access over HTTP, start the HTTP server and interact through the HTTP endpoints. Authentication is optional and can be enabled with a token.

To use the stdio transport, set the MCP_STDIO flag and start the dev server. Your client can then send commands via the standard input/output channel. To use the HTTP transport, start the HTTP server and use the exposed endpoints to create, read, update, or delete todos. Session management is built in for HTTP, and you can enable bearer token authentication if you need it.

Security note: if you enable token authentication, you must include the Authorization header in requests in the form Authorization: Bearer your-secret-token.

How to install

npm install
npm run build

Additional details

The HTTP transport exposes three endpoints for session-based interactions:

- POST /mcp for JSON-RPC requests - GET /mcp for an SSE stream of server notifications - DELETE /mcp to end the session

If you enable token authentication, set your token with the environment variable TODO_MCP_TOKEN and include a Bearer token in requests.

The server stores todos persistently at ~/.mcp-todos.json, ensuring your list is preserved across restarts.

Available tools

list_todos

Return all todos in a structured format with their IDs and completion status.

add_todo

Add a new todo by providing a title. The server creates a unique ID for the item and marks it as not completed by default.

toggle_todo

Toggle the completion status of a todo by its id.

remove_todo

Remove a todo by its id.