@pranavchavda/todo-mcp-server NPM

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

Start the server:
```
npx todo-mcp-server
```
Configure your MCP client to connect to the server via stdio

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