MCP Tasks

🚀 MCP Tasks 📋

An efficient task manager designed to minimize tool confusion and maximize LLM budget efficiency. It offers powerful search, filtering, and organization capabilities across multiple file formats (Markdown, JSON, YAML).

🚀 Quick Start

Add this to ~/.cursor/mcp.json for Cursor, ~/.config/claude_desktop_config.json for Claude Desktop.

Option 1: NPX (Recommended)

{
  "mcpServers": {
    "mcp-tasks": {
      "command": "npx",
      "args": ["-y", "mcp-tasks"]
    }
  }
}

Option 2: Docker

{
  "mcpServers": {
    "mcp-tasks": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "flesler/mcp-tasks"
      ]
    }
  }
}

✨ Features

• ⚡ Ultra-efficient design: With a minimal tool count (5 tools), it reduces AI confusion.
• 🎯 Budget-optimized: Batch operations, smart defaults, and auto-operations minimize LLM API calls.
• 🚀 Multi-format support: Supports Markdown (.md), JSON (.json), and YAML (.yml) task files.
• 🔍 Powerful search: Enables case-insensitive text/status filtering with OR logic and ID-based lookup.
• 📊 Smart organization: Allows status-based filtering with customizable workflow states.
• 🎯 Position-based indexing: Facilitates easy task ordering with 0-based insertion.
• 📁 Multi-source support: Manages multiple task files simultaneously.
• 🔄 Real-time updates: Automatically persists changes to your chosen format.
• 🤖 Auto WIP management: Automatically manages work-in-progress task limits.
• 🚫 Duplicate prevention: Automatically prevents duplicate tasks.
• 🛡️ Type-safe: Offers full TypeScript support with Zod validation.
• 🔒 Ultra-safe: AI has no way to rewrite or delete your tasks (unless you enable it), only add and move them.
• 📅 Optional reminders: Enables a dedicated Reminders section that the AI constantly sees and can maintain.

📦 Installation

Installation Examples

Full configuration with custom environment:

{
  "mcpServers": {
    "mcp-tasks": {
      "command": "npx",
      "args": ["-y", "mcp-tasks"],
      "env": {
        "STATUS_WIP": "In Progress",
        "STATUS_TODO": "To Do",
        "STATUS_DONE": "Done",
        "STATUS_REMINDERS": "Reminders",
        "STATUS_NOTES": "Notes",
        "STATUSES": "In Progress,To Do,Done,Backlog,Reminders,Notes",
        "AUTO_WIP": "true",
        "PREFIX_TOOLS": "true",
        "KEEP_DELETED": "true",
        "TRANSPORT": "stdio",
        "PORT": "4680",
        "INSTRUCTIONS": "Use mcp-tasks tools when the user mentions new or updated tasks"
      }
    }
  }
}

HTTP transport for remote access:

First run the server:

TRANSPORT=http PORT=4680 npx mcp-tasks

Then:

{
  "mcpServers": {
    "mcp-tasks": {
      "type": "streamableHttp",
      "url": "http://localhost:4680/mcp"
    }
  }
}

💻 Usage Examples

Basic Usage

To encourage the AI to use these tools, you can start with a prompt like the following, with any path you want with .md (recommended), .json, .yml:

Use mcp-tasks tools to track our work in path/to/tasks.md

If you are telling it about new or updated tasks, you can append this to the end of your prompt:

use mcp-tasks

Adding tasks while AI works: To safely add tasks without interfering with AI operations, use the CLI from a separate terminal:

npx mcp-tasks add "Your new task text" "To Do" 0

Advanced Usage

Setup a task file:

tasks_setup({
  workspace: "/path/to/project",
  source_path: "tasks.md"  // relative to workspace or absolute
  // source_path: "tasks.json"
  // source_path: "tasks.yml"
})
// Returns: {"source":{"id":"xK8p","path":"/path/to/project/tasks.md"},"Backlog":0,"To Do":0,"In Progress":0,"Done":0,"inProgress":[]}
// Source ID (4-char alphanumeric) is used for all subsequent operations

Add tasks:

tasks_add({
  source_id: "xK8p", // From setup response
  texts: ["Implement authentication", "Write tests"],
  status: "To Do",
  index: 0  // Add at top (optional)
})
// Returns: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":2,"In Progress":0,"Done":0,"inProgress":[],"tasks":[{"id":"m3Qw","text":"Implement authentication","status":"To Do","index":0},{"id":"p9Lx","text":"Write tests","status":"To Do","index":1}]}

Search and filter:

tasks_search({
  source_id: "xK8p",        // From setup response
  terms: ["auth", "deploy"],          // Search terms (text or status, OR logic)
  statuses: ["To Do"],      // Filter by status
  ids: ["m3Qw", "p9Lx"]     // Filter by specific task IDs
})
// Returns: [{"id":"m3Qw","text":"Implement authentication","status":"To Do","index":0}]

Update tasks status:

tasks_update({
  source_id: "xK8p",        // From setup response
  ids: ["m3Qw", "p9Lx"],    // Task IDs from add/search responses
  status: "Done"            // Use "Deleted" to remove
})
// Returns: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":0,"In Progress":0,"Done":2,"inProgress":[],"tasks":[{"id":"m3Qw","text":"Implement authentication","status":"Done","index":0},{"id":"p9Lx","text":"Write tests","status":"Done","index":1}]}

Get overview:

tasks_summary({
  source_id: "xK8p"         // From setup response
})
// Returns: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":0,"In Progress":1,"Done":2,"inProgress":[{"id":"r7Km","text":"Fix critical bug","status":"In Progress","index":0}]}

📚 Documentation

Supported File Formats

Format is auto-detected from file extension.

⚠️ Important Note

Start with a new file rather than using pre-existing task files to avoid losing non-task content.

Available Tools

When PREFIX_TOOLS=true (default), all tools are prefixed with tasks_:

ID Format: Both source_id (from file path) and task id (from task text) are 4-character alphanumeric strings (e.g., "xK8p", "m3Qw").

Environment Variables

Advanced Configuration Examples

Optional, the WIP/ToDo/Done statuses can be included to control their order.

Custom workflow statuses:

{
  "env": {
    "STATUSES": "WIP,Pending,Archived,Done,To Review",
    "STATUS_WIP": "WIP",
    "STATUS_TODO": "Pending",
    "AUTO_WIP": "false"
  }
}

File Formats

Markdown (.md) - Human-Readable

# Tasks - File Name

## In Progress
- [ ] Write user registration

## To Do
- [ ] Implement authentication
- [ ] Set up CI/CD pipeline

## Backlog
- [ ] Plan architecture
- [ ] Design database schema

## Done
- [x] Set up project structure
- [x] Initialize repository

## Reminders
- [ ] Don't move to Done until you verified it works
- [ ] After you move to Done, commit all the changes, use the task name as the commit message

## Notes
- [ ] The task tools were really great to use!

JSON (.json) - Structured Data

{
  "groups": {
    "In Progress": [
      "Write user registration"
    ],
    "To Do": [
      "Implement authentication",
      "Set up CI/CD pipeline"
    ],
    "Backlog": [
      "Plan architecture",
      "Design database schema"
    ],
    "Done": [
      "Set up project structure",
      "Initialize repository"
    ],
    "Reminders": [
      "Don't move to Done until you verified it works",
      "After you move to Done, commit all the changes, use the task name as the commit message"
    ],
    "Notes": [
      "The task tools were really great to use!"
    ]
  }
}

YAML (.yml) - Configuration-Friendly

groups:
  "In Progress":
    - Write user registration
  "To Do":
    - Implement authentication
    - Set up CI/CD pipeline
  Backlog:
    - Plan architecture
    - Design database schema
  Done:
    - Set up project structure
    - Initialize repository
  Reminders:
    - Don't move to Done until you verified it works
    - After you move to Done, commit all the changes, use the task name as the commit message

Server Usage

# Show help
mcp-tasks --help

# Default: stdio transport
mcp-tasks

# HTTP transport
TRANSPORT=http mcp-tasks
TRANSPORT=http PORT=8080 mcp-tasks

# Custom configuration
STATUS_WIP="Working" AUTO_WIP=false mcp-tasks

CLI Usage

You can also use mcp-tasks (or npx mcp-tasks) as a command-line tool for quick task management:

# Setup a task file
mcp-tasks setup tasks.md $PWD                      # Setup with workspace

# Add tasks
mcp-tasks add "Implement authentication"           # Defaults to "To Do" status
mcp-tasks add "Write tests" "Backlog"              # Add with specific status
mcp-tasks add "Fix critical bug" "In Progress" 0   # Add at top (index 0)

# Search tasks
mcp-tasks search                                    # All tasks
mcp-tasks search "" "auth,login"                   # Search for specific terms
mcp-tasks search "To Do,Done" ""                   # Filter by statuses
mcp-tasks search "In Progress" "bug"               # Filter by status and search terms

# Update task status (comma-separated IDs)
mcp-tasks update m3Qw,p9Lx Done

# Get summary
mcp-tasks summary

# Add a reminder (feature must be enabled with REMINDERS=true)
mcp-tasks add "Don't move to Done until you verified it works" Reminders

CLI Features:

• Direct access to all MCP tool functionality
• JSON output for easy parsing and scripting
• Same reliability and duplicate prevention as MCP tools
• Perfect for automation scripts and CI/CD pipelines

🔧 Technical Details

Development

# Clone and setup
git clone https://github.com/flesler/mcp-tasks
cd mcp-tasks
npm install

# Development mode (auto-restart)
npm run dev              # STDIO transport
npm run dev:http         # HTTP transport on port 4680

# Build and test
npm run build           # Compile TypeScript
npm run lint            # Check code style
npm run lint:full       # Build + lint

Troubleshooting

Requirements

• Node.js ≥20 - This package requires Node.js version 20 or higher

Common Issues

ERR_MODULE_NOT_FOUND when running npx-tasks

• Problem: Error like Cannot find module '@modelcontextprotocol/sdk/dist/esm/server/index.js' when running npx mcp-tasks
• Cause: Corrupt or incomplete npx cache preventing proper dependency resolution
• Solution: Clear the npx cache and try again:

  npx clear-npx-cache
  npx mcp-tasks
  

• Note: This issue can occur on both Node.js v20 and v22, and the cache clear resolves it

Where are my tasks stored?

• Tasks are stored in the file path you specified by the AI in tasks_setup
• The absolute path is returned in every tool call response under source.path
• If you forgot the location, check any tool response or ask the AI to show it to you

Lost content in Markdown files:

• ⚠️ The tools will rewrite the entire file, preserving only tasks under recognized status sections
• Non-task content (notes, documentation) may be lost when tools modify the file
• Use a dedicated task file rather than mixing tasks with other content

Why not just have AI edit the task files directly?

• File parsing complexity: AI must read entire files, parse markdown structure, and understand current state - expensive and error-prone
• Multi-step operations: Moving a task from "In Progress" to "Done" requires multiple read_file, grep_search, sed calls to locate and modify correct sections
• Context loss: Large task files forcing AI to work with incomplete chunks due to token restrictions and lose track of overall structure
• State comprehension: AI struggles to understand true project state when reading fragmented file sections - which tasks are actually in progress?
• Edit precision: Manual editing risks corrupting markdown formatting, losing tasks, or accidentally modifying the wrong sections
• Concurrent editing conflicts: When AI directly edits files, humans can't safely make manual changes without creating conflicts or overwrites
• Token inefficiency: Reading+parsing+editing cycles consume far more tokens than structured tool calls with clear inputs/outputs
• Safety: AI can accidentally change or delete tasks when directly editing files, but with these tools it cannot rewrite or delete your tasks

🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes with tests
4. Run: npm run lint:full
5. Submit a pull request

📄 License

MIT License - see LICENSE for details.

🔗 Links

• 📦 NPM Package
• 🐙 GitHub Repository
• 🐛 Report Issues
• 📚 MCP Specification
• ⚡ FastMCP Framework