MCP TODO Server

A robust Model Context Protocol (MCP) server built with NestJS, designed to manage TODO tasks and integrate seamlessly with AI agents like Claude Desktop, ChatGPT, and automation tools like n8n.

🚀 Features

✅ TODO Management: Full CRUD operations for tasks.
🤖 MCP Integration: Exposes TODO operations as MCP tools using both SSE (Server-Sent Events) and Stdio (via CLI integration).
📚 Swagger UI: Interactive API documentation at /api/docs.
🔍 MCP Inspector: Built-in support for debugging tools with the @modelcontextprotocol/inspector.
🛠️ Modern Tooling: Built with TypeScript, Biome for linting/formatting, and Jest for E2E testing.

🛠️ Tech Stack

Framework: NestJS
Protocol: Model Context Protocol (MCP)
Documentation: Swagger/OpenAPI
Linting/Formatting: Biome
Testing: Jest & Supertest

📋 Prerequisites

Node.js (v18 or higher)
npm

⚙️ Project Setup

# Install dependencies
$ npm install

# Create environment file
$ cp .env.example .env # Ensure SERVER_PORT=3000 is set

🏃 Compilation and Running

# Development (watch mode)
$ npm run start:dev

# Production mode
$ npm run build
$ npm run start:prod

📖 API Documentation

Once the server is running, you can access the interactive Swagger documentation at: http://localhost:3000/api/docs

🤖 Using with MCP Clients

1. ChatGPT Desktop (macOS)

Go to Settings > Advanced and enable Developer Mode.
Go to Settings > Connectors and click Create.
Set URL to http://localhost:3000/sse and Authentication to None.

2. MCP Inspector (Debugging)

To debug the MCP tools locally:

$ npm run inspector

This will open the MCP Inspector at http://localhost:3000/sse.

3. Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-todo": {
      "command": "node",
      "args": ["/path/to/project/dist/main.js"]
    }
  }
}

🧪 Testing

# Unit tests
$ npm run test

# End-to-end tests
$ npm run test:e2e

📄 License

This project is UNLICENSED.

mcp-server