Checklist MCP Server

Checklist MCP Server

An MCP (Model Context Protocol) server for managing hierarchical checklists and tracking work context, designed to help AI agents manage long-running tasks and maintain state across sessions.

Features

• Hierarchical Task Management: Create and manage nested checklists.
• Multi-tenancy Support: Built-in support for multiple isolated environments using namespaces.
• HTTP/SSE Transport: Uses the standard MCP HTTP transport with Server-Sent Events (SSE).

Tools

Tool Name	Description
init_tasks	Initialize a new checklist session. Requires the sessionId to NOT exist. If it exists, provides steering advice with a recommended available sessionId.
update_tasks	Create new tasks or overwrite existing tasks at a specific hierarchical path for an existing session.
mark_task_as_done	Mark specific tasks as completed in an existing session.
get_all_tasks	Retrieve the complete hierarchical list of tasks for an existing session.

Session Lifecycle & Steering Guidance

• Session Initialization: Call init_tasks first with a unique sessionId to create a checklist session.
• Session Isolation: Calling update_tasks, mark_task_as_done, or get_all_tasks with a non-existent sessionId will return non-error Steering guidance asking you to initialize the session first.
• Conflict Prevention: Calling init_tasks with an already existing sessionId will return non-error Steering guidance with a suggested alternative sessionId (e.g. my-session_1).

Quick Start

Running Locally (Node.js)

You can run the server directly using npx or npm.

Using npx:

npx checklist-mcp-server

Using npm:

git clone https://github.com/chene/checklist-mcp-server.git
cd checklist-mcp-server
npm install
npm run build
npm run start:http

The server will start on port 8585 by default.

Running with Docker

docker run -d -p 8585:8585 --name checklist-mcp-server checklist-mcp-server:latest

For more detailed Docker instructions, see DOCKER.md.

Configuration

MCP Client Configuration

Configure your MCP client (e.g., Claude Desktop, custom agent) to connect to the HTTP endpoint.

{
  "mcpServers": {
    "checklist": {
      "transport": "http",
      "url": "http://localhost:8585/mcp"
    }
  }
}

Multi-tenancy (Namespaces)

This server supports multi-tenancy via the namespace query parameter. This allows multiple agents or users to store distinct data within the same server instance.

To use a specific namespace, append ?namespace=<your_namespace> to the server URL.

Example Client Config for a specific namespace:

{
  "mcpServers": {
    "project-alpha": {
      "transport": "http",
      "url": "http://localhost:8585/mcp?namespace=project-alpha"
    },
    "project-beta": {
      "transport": "http",
      "url": "http://localhost:8585/mcp?namespace=project-beta"
    }
  }
}

If no namespace is provided, the server defaults to the default namespace.

License

MIT