MCP Task Management Server

An advanced Model Context Protocol (MCP) server for comprehensive task management with groups, custom statuses, task relationships, and AI integration. Now powered by SQLite for enhanced performance and reliability.

Features

• Task Management: Create, update, delete, and search tasks with rich metadata
• Bulk Operations: Create, update, and change status of multiple tasks simultaneously
• Task Groups: Organize tasks into projects, areas, or any custom groupings
• Custom Statuses: Define your own workflow statuses with colors and descriptions
• Task References: Create relationships between tasks (blocks, relates-to, child-of, etc.)
• Status History: Automatic tracking of status changes with timestamps
• Markdown Support: Task descriptions support full markdown formatting
• AI-Friendly: Designed for AI assistants to automatically manage tasks during conversations
• Persistent Storage: SQLite database with automatic migration from JSON format

Installation

1. Clone or download this repository
2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Usage

As an MCP Server

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "mcp-task": {
      "command": "node",
      "args": ["/path/to/mcp-task/build/index.js"]
    }
  }
}

Direct Usage

You can also run the server directly:

npm start

Data Storage

SQLite Database (Default)

The server now uses SQLite as the default database for improved performance, reliability, and data integrity. Tasks are stored in ~/.mcp-tasks.sqlite.

Benefits of SQLite:

• Better performance for large datasets
• ACID transactions ensure data consistency
• Structured queries and indexing
• Automatic migration from JSON format

Legacy JSON Support

For compatibility, the server can still use JSON storage by setting the environment variable:

export MCP_TASK_USE_SQLITE=false

Automatic Migration: When upgrading from JSON to SQLite, the server automatically migrates your existing ~/.mcp-tasks.json data to the new SQLite format.

Available Tools

Task Operations

• create_task: Create a new task with title, description, status, group, priority, tags, assignee, due date, and time estimates
• update_task: Update any task properties. Status changes are automatically tracked with timestamps
• get_task: Get detailed task information including history and references
• list_tasks: List and filter tasks by status, group, assignee, tags, priority, due dates, or search terms
• delete_task: Delete a task and remove all references to it

Bulk Operations

• bulk_create_tasks: Create multiple tasks at once with shared properties (group, status, assignee, tags)
• bulk_update_tasks: Update multiple tasks simultaneously with the same changes
• bulk_change_status: Change the status of multiple tasks at once with optional notes

Group Management

• create_group: Create task groups for organizing related tasks (projects, areas, etc.)
• list_groups: List all groups with metadata
• delete_group: Delete a group (tasks remain but become ungrouped)

Status Management

• create_status: Create custom workflow statuses with colors and descriptions
• list_statuses: List all available statuses
• delete_status: Delete custom statuses (cannot delete default or in-use statuses)

Task Relationships

• add_task_reference: Create relationships between tasks:
  • blocks / blocked-by: Dependency relationships
  • relates-to: General relationship
  • duplicates: Duplicate tasks
  • child-of / parent-of: Hierarchical relationships
• remove_task_reference: Remove task relationships
• get_task_references: View all incoming and outgoing task references

AI Integration

This MCP server is specifically designed for AI assistants to:

1. Automatically create tasks when users mention work they need to do
2. Update task status as work progresses during conversations
3. Break down complex requests into manageable subtasks with references
4. Track project progress by organizing tasks into groups
5. Manage dependencies by creating task references
6. Provide context by searching and filtering existing tasks
7. Handle bulk operations for efficient project setup and team management

Example AI Usage Patterns

Creating tasks from conversation:

User: "I need to implement user authentication and then build the dashboard"
AI: Creates two tasks:
- "Implement user authentication"
- "Build dashboard" (with "blocked-by" reference to auth task)

Status tracking:

User: "I finished the login form"
AI: Updates relevant task status to "Done" and adds completion timestamp

Project organization:

User: "Let's start working on the mobile app redesign"
AI: Creates a "Mobile App Redesign" group and organizes related tasks

Bulk project setup:

User: "I need to set up tasks for the Q1 marketing campaign"
AI: Uses bulk_create_tasks to create multiple related tasks at once:
- "Design campaign assets", "Write copy", "Set up analytics", etc.

Team workflow management:

User: "Move all the design tasks to review status"
AI: Uses bulk_change_status to transition multiple tasks simultaneously

Data Model

Task Properties

• Basic Info: ID, title, description, summary
• Organization: status, group, priority, tags, assignee
• Timing: due date, estimated hours, actual hours
• Tracking: created/updated timestamps, completion date
• Relationships: references to other tasks
• History: Complete status change history

Task Statuses

Default statuses include "To Do", "In Progress", and "Done", but you can create custom statuses like "Review", "Testing", "Blocked", etc.

Task Groups

Organize tasks into logical groups like:

• Projects ("Website Redesign", "Mobile App")
• Areas ("Marketing", "Development", "Operations")
• Contexts ("Home", "Office", "Travel")

Task References

Model complex relationships:

• Dependencies: Task A blocks Task B
• Hierarchy: Parent/child task relationships
• Related work: Tasks that relate to each other
• Duplicates: Mark duplicate tasks

Complete Tool Reference

The server provides 17 comprehensive tools designed for AI assistants:

Task Operations: create_task, update_task, get_task, list_tasks, delete_task Bulk Operations: bulk_create_tasks, bulk_update_tasks, bulk_change_status Groups: create_group, list_groups, delete_group Statuses: create_status, list_statuses, delete_status References: add_task_reference, remove_task_reference, get_task_references

Bulk Operations in Detail

bulk_create_tasks: Perfect for project initialization, breaking down large initiatives into subtasks, or importing task lists. Supports shared properties (group, status, assignee, tags) that apply to all tasks while allowing individual task customization.

bulk_update_tasks: Ideal for team management scenarios like reassigning multiple tasks, updating priorities across a project, or applying deadline changes to related tasks.

bulk_change_status: Essential for workflow management such as moving multiple tasks through pipeline stages, marking sprint tasks as complete, or transitioning project phases.

Each tool includes comprehensive error handling, detailed result reporting, and maintains data integrity even during partial failures.

Development

Build

npm run build

Development mode with auto-rebuild

npm run dev

Project Structure

src/
├── types.ts      # TypeScript type definitions
├── database.ts   # Data persistence and management
└── index.ts      # MCP server implementation

License

ISC License