MCP Todo Server

A distributed MCP server for task prioritization with AI-powered analysis.

Quick Start

# Set your OpenRouter API key
echo "OPENROUTER_API_KEY=your-api-key" > .env

# Start the stack
docker compose up --build -d

Server runs at http://localhost:3000/mcp

Related MCP server: TickTick MCP Server

Example Usage

Adding TODOs

Analyzing TODOs

Marking TODO as done

Removing TODO

Clearing TODOs

Architecture

• 2 Node instances behind Caddy load balancer (round-robin)

• Redis for shared state (no sticky sessions required)

• OpenRouter for AI-powered task analysis

MCP Tools

Client Setup

⚠️ User Isolation: Set the x-user-id header to isolate your todos. Without it, todos are shared with all users.

⚠️ Important: Before starting your full conversation at any given client, you should start by sending message that you want to use MCP tools from this MCP server.

For example in OpenCode the tools have the prefix todo-mcp due to the name of the MCP server in the config. See example first message would be: For this conversation I want you to use MCP tools starting with todo-mcp.

Reason why is that because most of the clients will have their TODO implementation already and it could mix up.

Cursor

Disclaimer

After adding the MCP server to Cursor, Cursor will be saying that the server is not available and there is error. The logs show that it is looking for SSE connections but still manages to connect and use the tools. Ignore that for now. It might be Cursor bug, could be reported to them.

Or manually add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "todo-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "x-user-id": "your-unique-user-id"
      }
    }
  }
}

Or manually add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "todo-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

VS Code

{
  "servers": {
    "todo-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "x-user-id": "your-unique-user-id"
      }
    }
  }
}

{
  "servers": {
    "todo-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "todo-mcp": {
      "type": "remote",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "x-user-id": "your-unique-user-id"
      },
      "enabled": true
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "todo-mcp": {
      "type": "remote",
      "url": "http://localhost:3000/mcp",
      "enabled": true
    }
  }
}

Endpoints

• POST /mcp - MCP protocol endpoint

• GET /health - Health check

Environment Variables

Development

npm install
npm run dev

User Isolation

Todos are isolated per user via the x-user-id header:

• Redis keys: todo:{userId}:{id} and todos:{userId}

• No sticky sessions required - any node can handle any request

• Without the header, requests are associated with a shared default user (no 401 is returned)

The user isolation is implemented in a dummy manner. Usage of API key would be better and preferred but I wanted to keep it simple and focus on the MCP server implementation.

Load Balancing

Caddy distributes requests round-robin across both nodes. All state is in Redis.

Testing

Unit and integration tests.

npm test