Todo MCP Server

★ 1

from Xczer

A Todo and Task Manager server for creating, updating, and managing tasks, using a SQLite database.

🔥🔥✓ VerifiedFreeAdvanced setup

Todo MCP Server

A comprehensive Todo/Task Manager MCP (Model Context Protocol) Server built with Node.js, TypeScript, and SQLite. This server provides tools, resources, and prompts for managing todos through Claude and other MCP-compatible clients.

Features

🛠️ Tools (7 available)

create_todo - Create new todos with title, description, priority, due date, and tags
update_todo - Update existing todos (any field)
delete_todo - Delete todos by ID
complete_todo - Mark todos as completed
list_todos - List todos with filtering (completion status, priority, tag, limit)
search_todos - Search todos by title, description, or tags
get_todo_stats - Get comprehensive todo statistics

📄 Resources (9 available)

todos://all - All todos (JSON)
todos://completed - Completed todos (JSON)
todos://pending - Pending todos (JSON)
todos://overdue - Overdue todos (JSON)
todos://todo/{id} - Specific todo by ID (JSON)
todos://priority/{priority} - Todos by priority (JSON) with autocomplete
todos://tag/{tag} - Todos by tag (JSON) with autocomplete
todos://stats - Todo statistics (JSON)
todos://tags - All available tags (JSON)

💬 Prompts (5 available)

create_todo_prompt - Interactive todo creation
daily_review - Daily todo review and planning
weekly_planning - Weekly planning session
productivity_analysis - Analyze productivity patterns
task_breakdown - Break down complex tasks

API Examples

Creating a Todo

// Using the create_todo tool
{
  "title": "Review documentation",
  "description": "Read through the MCP protocol documentation",
  "priority": "high",
  "dueDate": "2024-06-27T10:00:00.000Z",
  "tags": ["work", "learning"]
}

Filtering Todos

// Using the list_todos tool
{
  "completed": false,
  "priority": "high",
  "limit": 10
}

Resource Access

GET todos://pending          # All pending todos
GET todos://priority/high    # High priority todos
GET todos://tag/work         # Todos tagged with "work"
GET todos://stats            # Todo statistics

Architecture

src/
├── database.ts        # SQLite database layer with better-sqlite3
├── index.ts          # Main server entry point
├── mcp-server.ts     # MCP server implementation
├── todo-service.ts   # Business logic layer
├── test.ts          # Test suite
└── types.ts         # TypeScript type definitions

Key Components

TodoDatabase - Direct SQLite interface with better-sqlite3
TodoService - Business logic with validation and error handling
TodoMcpServer - MCP protocol implementation with tools, resources, and prompts

Development

Scripts

npm run build - Compile TypeScript to JavaScript
npm run dev - Development mode with file watching
npm start - Start the production server
npm run test - Run the test suite

Technology Stack

Runtime: Node.js
Language: TypeScript
Database: SQLite with better-sqlite3
Protocol: Model Context Protocol (MCP)
Validation: Zod schemas

Testing

The project includes comprehensive testing:

npm run test

This will:

Create an in-memory database
Test all CRUD operations
Verify search and filtering functionality
Check statistics generation
Validate tag management

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request

Changelog

v1.0.0

Initial release
Complete MCP implementation with tools, resources, and prompts
SQLite database with better-sqlite3
Comprehensive test suite
Node.js compatibility (migrated from Bun)

Copy & paste — that's it

npm install

Before it works, you'll need: TODO_DB_PATH

Installation

Clone or create the project directory:
```
mkdir todo-mcp-server
cd todo-mcp-server
```
Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```

Usage

Basic Server Operations

Test the todo service:
```
npm run test
```
Run the MCP server:
```
npm start
```
Development mode (with file watching):
```
npm run dev
```

Testing with MCP Inspector

Start the inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Open the web interface:
- Follow the URL provided in the terminal output
- Use the provided authentication token

Claude Desktop Integration

Add this configuration to your Claude Desktop config file:

{
  "mcpServers": {
    "todo-manager": {
      "command": "node",
      "args": ["/path/to/todo-mcp-server/dist/index.js"],
      "env": {
        "TODO_DB_PATH": "/path/to/your/todos.db"
      }
    }
  }
}

Configuration

Environment Variables

TODO_DB_PATH: Path to SQLite database file (default: todos.db in current directory)

Database

The server uses SQLite with better-sqlite3 for data persistence. The database is automatically created with the following schema:

todos table with fields: id, title, description, completed, priority, due_date, tags, created_at, updated_at
Indexes on completion status, priority, due date, and creation date for optimal performance

Troubleshooting

Common Issues

Database permission errors: Ensure the directory is writable
Port conflicts: The MCP server uses stdio, no ports needed
TypeScript errors: Run npm run build to check for compilation issues

Debugging

Enable debug logging by setting:

export DEBUG=todo-mcp-server