README.md•4.2 kB
# 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
```bash
npm install
```
## Setup
1. Create a `.env` file in the project root:
```env
DATABASE_URL="file:./dev.db"
```
2. Initialize the database:
```bash
npx prisma migrate dev
```
3. Configure Claude Desktop by adding this to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```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:
```bash
npm run mcp:todo
```
Test with a JSON-RPC message:
```bash
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:
```bash
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
```prisma
model Todo {
id String @id @default(uuid())
title String
done Boolean @default(false)
due String?
createdAt DateTime @default(now())
}
```
### Migrations
```bash
# 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:
```bash
npm run dev
```
Open [http://localhost:3000](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](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
Check out the [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
## Tech Stack
- **MCP SDK**: [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk)
- **Database**: SQLite + Prisma
- **Runtime**: Node.js with tsx for TypeScript execution
- **Frontend** (optional): Next.js 15, React 19, Tailwind CSS
## License
MIT