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
.envfile 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 titledue(string, optional): Due date
toggle_todo
Toggles or sets the completion status of a todo.
id(string, required): Todo IDdone(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