Todo MCP Server

A comprehensive Model Context Protocol (MCP) server for to-do list management in agentic workflows. This server enables LLM agents to track tasks, manage workflows, and maintain conversation context throughout complex multi-step processes.

Features

• Task Management: Create, update, delete, and track tasks with rich metadata
• Conversation Threading: Associate tasks with specific conversation threads
• Priority & Categorization: Organize tasks by priority levels and categories
• Status Tracking: Monitor task progress through different states
• Agentic Workflow Support: Designed specifically for AI agent task management
• MCP Compliance: Full Model Context Protocol implementation
• SQLite Persistence: Reliable local data storage
• Rich Prompts: Built-in templates for planning and progress review

Installation

Using npx (Recommended)

npx todo-mcp-server

Global Installation

npm install -g todo-mcp-server
todo-mcp-server

Local Development

git clone https://github.com/manus-ai/todo-mcp-server.git
cd todo-mcp-server
npm install
npm run build
npm start

Quick Start

1. Start the server:

   npx todo-mcp-server

2. Configure your MCP client to connect to the server via stdio

3. Create your first task:

   {
     "method": "tools/call",
     "params": {
       "name": "create_task",
       "arguments": {
         "title": "Set up project structure",
         "description": "Initialize the basic project structure and dependencies",
         "priority": 4,
         "category": "development"
       }
     }
   }

Configuration

The server accepts the following command-line options:

• -d, --database <path>: Specify database file path (default: ./todo.db)

Example:

todo-mcp-server --database /path/to/my/tasks.db

MCP Tools

Task Management

create_task

Create a new task with optional metadata.

Parameters:

• title (required): Task title
• description: Detailed task description
• priority: Priority level (1-5, default: 3)
• category: Task category
• tags: Array of tags
• due_date: Due date in ISO format
• conversation_id: Associated conversation ID
• parent_task_id: Parent task for subtasks

update_task

Update an existing task.

Parameters:

• task_id (required): Task ID to update
• title: New task title
• description: New task description
• status: Task status (pending, in_progress, completed, blocked)
• priority: Priority level (1-5)
• category: Task category
• tags: Array of tags
• due_date: Due date in ISO format

delete_task

Delete a task by ID.

Parameters:

• task_id (required): Task ID to delete

complete_task

Mark a task as completed.

Parameters:

• task_id (required): Task ID to complete

list_tasks

List tasks with optional filtering.

Parameters:

• conversation_id: Filter by conversation ID
• status: Filter by status
• category: Filter by category
• priority_min: Minimum priority level
• priority_max: Maximum priority level
• limit: Maximum number of tasks to return
• offset: Number of tasks to skip

Conversation Management

create_conversation

Create a new conversation thread.

Parameters:

• title: Conversation title
• description: Conversation description
• agent_id: Agent identifier

Analytics

get_task_statistics

Get task completion statistics.

Parameters:

• conversation_id: Filter by conversation ID
• date_range: Date range (e.g., "7d", "30d", "1y")

MCP Resources

todo://tasks

Access to all tasks in JSON format.

todo://conversations

Access to all conversation threads in JSON format.

MCP Prompts

daily_planning

Template for daily task planning and organization.

project_breakdown

Template for breaking down complex projects into manageable tasks.

progress_review

Template for reviewing progress and planning next steps.

Database Schema

The server uses SQLite with the following schema:

Tasks Table

• id: Primary key
• title: Task title
• description: Task description
• status: Task status (pending, in_progress, completed, blocked)
• priority: Priority level (1-5)
• category: Task category
• tags: JSON array of tags
• created_at: Creation timestamp
• updated_at: Last update timestamp
• due_date: Due date
• completed_at: Completion timestamp
• conversation_id: Associated conversation ID
• agent_id: Agent identifier
• parent_task_id: Parent task ID for subtasks
• metadata: JSON metadata

Conversations Table

• id: Primary key (UUID)
• title: Conversation title
• description: Conversation description
• agent_id: Agent identifier
• created_at: Creation timestamp
• updated_at: Last update timestamp
• status: Conversation status (active, archived, completed)
• metadata: JSON metadata

Task Dependencies Table

• id: Primary key
• task_id: Task ID
• depends_on_task_id: Dependency task ID
• dependency_type: Dependency type (blocks, requires, related)
• created_at: Creation timestamp

API Examples

Creating a Task

{
  "method": "tools/call",
  "params": {
    "name": "create_task",
    "arguments": {
      "title": "Research MCP specification",
      "description": "Study the Model Context Protocol documentation and examples",
      "priority": 5,
      "category": "research",
      "tags": ["mcp", "documentation"],
      "due_date": "2024-12-31T23:59:59Z",
      "conversation_id": "conv-123"
    }
  }
}

Listing Tasks

{
  "method": "tools/call",
  "params": {
    "name": "list_tasks",
    "arguments": {
      "conversation_id": "conv-123",
      "status": "pending",
      "priority_min": 3,
      "limit": 10
    }
  }
}

Getting Statistics

{
  "method": "tools/call",
  "params": {
    "name": "get_task_statistics",
    "arguments": {
      "conversation_id": "conv-123",
      "date_range": "7d"
    }
  }
}

Integration with MCP Clients

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "todo": {
      "command": "npx",
      "args": ["todo-mcp-server"],
      "env": {}
    }
  }
}

Custom MCP Client

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['todo-mcp-server']
});

const client = new Client({
  name: "my-client",
  version: "1.0.0"
}, {
  capabilities: {}
});

await client.connect(transport);

Development

Project Structure

todo-mcp-server/
├── src/
│   ├── index.ts          # Main server entry point
│   ├── database.ts       # Database layer
│   └── todo-manager.ts   # Business logic
├── dist/                 # Compiled JavaScript
├── tests/               # Test files
├── docs/                # Documentation
├── examples/            # Usage examples
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Testing

npm test

Linting

npm run lint

Formatting

npm run format

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run linting and tests
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• GitHub Issues: https://github.com/manus-ai/todo-mcp-server/issues
• Documentation: https://github.com/manus-ai/todo-mcp-server/docs
• Examples: https://github.com/manus-ai/todo-mcp-server/examples

Changelog

v0.1.0

• Initial release
• Basic task management functionality
• MCP protocol compliance
• SQLite persistence
• Conversation threading
• Built-in prompts for planning and review