MCP Todo

A todo list server built with the Model Context Protocol (MCP) that supports both stdio and HTTP transports.

Quick Start

npm install

# For HTTP server (easier testing)
npm run dev:http

# For MCP stdio (client integration)
MCP_STDIO=1 npm run dev

Setup

npm install
npm run build

Usage

Stdio Transport (MCP Client Integration)

For use with MCP clients like Cursor:

MCP_STDIO=1 npm run dev

Configure in Cursor's .cursor/mcp.json:

{
  "mcpServers": {
    "todo-mcp": {
      "command": "npx",
      "args": ["-y", "tsx", "src/server.ts"],
      "env": {
        "MCP_STDIO": "1"
      }
    }
  }
}

HTTP Transport (Streamable HTTP)

For HTTP-based access with session management:

npm run dev MCP_STDIO=1 # Starts MCP stdio server
npm run dev:http  # Starts HTTP server on port 3000
# or directly: npx tsx src/http.ts

The server exposes endpoints at http://localhost:3000/mcp:

POST /mcp - JSON-RPC requests
GET /mcp - SSE stream for server notifications
DELETE /mcp - End session

Authentication

Set TODO_MCP_TOKEN environment variable to enable bearer token authentication:

TODO_MCP_TOKEN=your-secret-token npm run dev

Then include in requests:

Authorization: Bearer your-secret-token

Features

Add todos with unique IDs
List all todos with structured output
Toggle todo completion status
Remove todos by ID
Persistent JSON storage in ~/.mcp-todos.json
Session-based HTTP transport with SSE support
Optional bearer token authentication

Available Tools

list_todos - Get all todos in structured format
add_todo - Add a new todo (requires title)
toggle_todo - Toggle completion status (requires id)
remove_todo - Delete a todo (requires id)

Resources

todos://list - JSON resource containing all todos

Architecture

src/server.ts - Core MCP server with todo logic and stdio transport
src/http.ts - HTTP transport wrapper with Express and session management