MCP Todo Server

You run a distributed MCP Todo Server to manage tasks across multiple nodes with shared state in Redis and AI-powered prioritization via OpenAI. It exposes an MCP endpoint for clients to add, list, complete, and analyze tasks, while balancing load across several nodes for reliability and scalability.

How to use

Connect your MCP client to the Todo server using either the HTTP MCP endpoint or the local runtime you run yourself. You can add tasks with priorities, list tasks by status, mark tasks as done, remove specific tasks, clear all tasks, and request AI-powered prioritization to optimize your backlog. Your client can also subscribe to real-time updates via the server’s MCP channel.

How to install

# Prerequisites
- Docker and Docker Compose
- Node.js 18+ (for local development)
- OpenAI API key

# Quick start using Docker Compose
- Ensure you have the source checked out
- Copy and customize environment variables
  cp .env.example .env
  # Edit .env and set OPENAI_API_KEY and REDIS_URL if needed

- Start the multi-node stack
- docker compose up --build

- Verify health
- curl http://localhost:3000/health

For local development without Docker, install dependencies and run the dev server as described in the development flow. This starts a local MCP server node that connects to Redis and exposes the MCP endpoint for testing and experimentation.

Additional sections

Configuration and runtime details help you tailor the server to your needs. The setup includes an HTTP-MCP entrypoint and a local stdio runtime you can invoke for development. You also get health checks, graceful shutdown, and an architecture that scales by adding more nodes behind a load balancer.

MCP connection configurations you can use right away are shown below. This includes an HTTP endpoint for remote clients and a local, development runtime you can execute from your environment. The HTTP endpoint is the preferred start point for clients that communicate over the MCP protocol.

{
  "mcpServers": {
    "todo": {
      "type": "http",
      "name": "todo_http",
      "url": "http://localhost:3000/mcp",
      "args": []
    }
  }
}

{
  "mcpServers": {
    "todo_dev": {
      "type": "stdio",
      "name": "todo_dev",
      "command": "npm",
      "args": ["run", "dev"],
      "env": [
        {"name": "REDIS_URL", "value": "redis://localhost:6379"},
        {"name": "OPENAI_API_KEY", "value": "YOUR_OPENAI_API_KEY"},
        {"name": "NODE_ID", "value": "dev-node"}
      ]
    }
  }
}

Available tools

todo_add

Add new tasks with a priority level to the shared task list.

todo_list

List tasks with optional status filters such as pending, done, or all.

todo_remove

Remove a specific task by its identifier.

todo_clear

Clear all tasks from the list.

todo_mark_done

Mark one or more tasks as completed.

todo_analyze

Request AI-powered prioritization to reorder tasks based on importance and urgency.