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

Create a .env file in the project root:

DATABASE_URL="file:./dev.db"

Initialize the database:

npx prisma migrate dev

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" } } } }

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

This server cannot be installed

-

security - not tested

-

license - not tested

-

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables Claude to manage todo lists with full CRUD operations including creating, listing, toggling completion status, deleting, and searching todos. Uses SQLite database with Prisma ORM for reliable data persistence and includes optional due date functionality.

Todo MCP Server