MCP Todo Server

A simple Model Context Protocol (MCP) server that provides todo list management functionality to Claude Desktop and other MCP clients.

Features

• Create todos with optional due dates

• List all todos sorted by creation date

• Toggle todo completion status

• Delete todos by ID

• Search todos by title

• SQLite database with Prisma ORM for reliable concurrent operations

Installation

npm install

Setup

1. Create a .env file in the project root:

DATABASE_URL="file:./dev.db"

2. Initialize the database:

npx prisma migrate dev

3. Configure Claude Desktop by adding this to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "todo": {
      "command": "bash",
      "args": ["/absolute/path/to/mcp-todo/mcp/run-todo.sh"],
      "env": {
        "DATABASE_URL": "file:/absolute/path/to/mcp-todo/data/todos.db"
      }
    }
  }
}

4. Restart Claude Desktop

Project Structure

mcp-todo/
├── mcp/
│   ├── todo-server.ts       # MCP server implementation
│   └── run-todo.sh          # Server startup script
├── lib/
│   └── todos.ts             # Todo business logic with Prisma
├── prisma/
│   ├── schema.prisma        # Database schema
│   └── migrations/          # Database migrations
├── data/
│   └── todos.db             # SQLite database file
└── src/                     # Next.js app (optional UI)

Available MCP Tools

list_todos

Returns all todos sorted by creation date (newest first).

add_todo

Creates a new todo item.

• title (string, required): The todo title

• due (string, optional): Due date

toggle_todo

Toggles or sets the completion status of a todo.

• id (string, required): Todo ID

• done (boolean, optional): Set specific state, or omit to toggle

delete_todo

Deletes a todo by ID.

• id (string, required): Todo ID

search_todos

Search todos by title substring.

• q (string, required): Search query

Development

Run the MCP server directly:

npm run mcp:todo

Test with a JSON-RPC message:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | npm run mcp:todo

Debug with MCP Inspector

Use the MCP Inspector to test and debug your server interactively:

npx @modelcontextprotocol/inspector npm run mcp:todo

This opens a web interface where you can test all available tools and see real-time request/response data.

Database

The project uses SQLite with Prisma ORM. The database file is stored at data/todos.db.

Schema

model Todo {
  id        String   @id @default(uuid())
  title     String
  done      Boolean  @default(false)
  due       String?
  createdAt DateTime @default(now())
}

Migrations

# Create a new migration
npx prisma migrate dev --name migration_name

# Reset database
npx prisma migrate reset

# View database in Prisma Studio
npx prisma studio

Next.js Web UI (Optional)

This project also includes a Next.js web interface for managing todos.

Getting Started

Run the development server:

npm run dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying src/app/page.tsx. The page auto-updates as you edit the file.

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out the Next.js deployment documentation for more details.

Tech Stack

• MCP SDK: @modelcontextprotocol/sdk

• Database: SQLite + Prisma

• Runtime: Node.js with tsx for TypeScript execution

• Frontend (optional): Next.js 15, React 19, Tailwind CSS

License

MIT