MCP Tasks

MCP Tasks 📋

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

📚 Table of Contents

✨ Features

⚡ Ultra-efficient design: Minimal tool count (5 tools) to reduce AI confusion
🎯 Budget-optimized: Batch operations, smart defaults and auto-operations minimize LLM API calls
🚀 Multi-format support: Markdown (.md), JSON (.json), and YAML (.yml) task files
🔍 Powerful search: Case-insensitive text/status filtering with OR logic, and ID-based lookup
📊 Smart organization: Status-based filtering with customizable workflow states
🎯 Position-based indexing: Easy task ordering with 0-based insertion
📁 Multi-source support: Manage multiple task files simultaneously
🔄 Real-time updates: Changes persist automatically to your chosen format
🤖 Auto WIP management: Automatically manages work-in-progress task limits
🚫 Duplicate prevention: Automatically prevents duplicate tasks
🛡️ Type-safe: 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: Enable a dedicated Reminders section the AI constantly sees and can maintain

🚀 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"
      ]
    }
  }
}

🤖 AI Integration Tips

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

🔧 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"
    }
  }
}

📁 Supported File Formats

Extension	Format	Best For	Auto-Created
`.md`	Markdown	Human-readable task lists	✅
`.json`	JSON	Structured data, APIs	✅
`.yml`	YAML	Configuration files	✅

Format is auto-detected from file extension. All formats support the same features and can be mixed in the same project.

Recommended: Markdown (.md) for human readability and editing

⚠️ Warning: 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_:

Tool	Description	Parameters
`tasks_setup`	Initialize a task file (creates if missing, supports `.md`, `.json`, `.yml`)	`source_path`, `workspace?`
`tasks_search`	Search tasks with filtering	`source_id`, `statuses?`, `terms?`, `ids?`
`tasks_add`	Add new tasks to a status	`source_id`, `texts[]`, `status`, `index?`
`tasks_update`	Update tasks by ID	`source_id`, `ids[]`, `status`, `index?`
`tasks_summary`	Get task counts and work-in-progress	`source_id`

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

Tool Examples

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}]}

🎛️ Environment Variables

Variable	Default	Description
`TRANSPORT`	`stdio`	Transport mode: `stdio` or `http`
`PORT`	`4680`	HTTP server port (when `TRANSPORT=http`)
`PREFIX_TOOLS`	`true`	Prefix tool names with `tasks_`
`STATUS_WIP`	`In Progress`	Work-in-progress status name
`STATUS_TODO`	`To Do`	ToDo status name
`STATUS_DONE`	`Done`	Completed status name
`STATUS_REMINDERS`	`Reminders`	Reminders for the AI (empty string to disable)
`STATUS_NOTES`	`Notes`	Notes/non-actionable tasks (empty string to disable)
`STATUSES`	`Backlog`	Comma-separated additional statuses
`AUTO_WIP`	`true`	One WIP moves rest to To Do, first To Do to WIP when no WIP's
`KEEP_DELETED`	`true`	Retain deleted tasks (AI can't lose you tasks!)
`INSTRUCTIONS`	`...`	Included in all tool responses, for the AI to follow
`SOURCES_PATH`	`./sources.json`	File to store source registry (internal)
`DEBUG`	`false`	if true, enable the `tasks_debug` tool

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

🧪 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:

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

📄 License

MIT License - see LICENSE for details.

🔗 Links

Install Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

A comprehensive and efficient Model Context Protocol server for task management that works with Claude, Cursor, and other MCP clients, providing powerful search, filtering, and organization capabilities across multiple file formats.

Related MCP Servers

@kazuph/mcp-taskmanager
kazuph
A
security
A
license
A
quality
Model Context Protocol server for Task Management. This allows Claude Desktop (or any MCP client) to manage and execute tasks in a queue-based system.
Last updated -
10
1,147
167
JavaScript
MIT License
Calculator MCP Server
QuantGeekDev
-
security
F
license
-
quality
A Model Context Protocol server built with mcp-framework that allows users to create and manage custom tools for processing data, integrating with the Claude Desktop via CLI.
Last updated -
32
5
TypeScript
MCP TaskManager
Rudra-ravi
A
security
A
license
A
quality
A Model Context Protocol server that allows Claude Desktop to manage and execute tasks in a queue-based system, supporting planning, execution, and completion phases.
Last updated -
10
1,147
5
TypeScript
MIT License
Todoist MCP Server
stevengonsalvez
-
security
A
license
-
quality
A Model Context Protocol server that enables advanced task and project management in Todoist via Claude Desktop and other MCP-compatible clients.
Last updated -
569
1
JavaScript
MIT License

View all related MCP servers

MCP Tasks

MCP Tasks 📋

📚 Table of Contents

✨ Features

🚀 Quick Start

Option 1: NPX (Recommended)

Option 2: Docker

🤖 AI Integration Tips

🔧 Installation Examples

📁 Supported File Formats

🛠️ Available Tools

Tool Examples

🎛️ Environment Variables

Advanced Configuration Examples

📊 File Formats

Markdown (`.md`) - Human-Readable

JSON (`.json`) - Structured Data

YAML (`.yml`) - Configuration-Friendly

🖥️ Server Usage

💻 CLI Usage

🧪 Development

🛠️ Troubleshooting

Requirements

Common Issues

Why not just have AI edit the task files directly?

🤝 Contributing

📄 License

🔗 Links

Tools

Related MCP Servers

@kazuph/mcp-taskmanager

Calculator MCP Server

MCP TaskManager

Todoist MCP Server

New MCP Servers

MCP directory API

MCP Tasks 📋

📚 Table of Contents

✨ Features

🚀 Quick Start

Option 1: NPX (Recommended)

Option 2: Docker

🤖 AI Integration Tips

🔧 Installation Examples

📁 Supported File Formats

🛠️ Available Tools

Tool Examples

🎛️ Environment Variables

Advanced Configuration Examples

📊 File Formats

Markdown (.md) - Human-Readable

JSON (.json) - Structured Data

YAML (.yml) - Configuration-Friendly

🖥️ Server Usage

💻 CLI Usage

🧪 Development

🛠️ Troubleshooting

Requirements

Common Issues

Why not just have AI edit the task files directly?

🤝 Contributing

📄 License

🔗 Links

Tools

Related MCP Servers

@kazuph/mcp-taskmanager

Calculator MCP Server

MCP TaskManager

Todoist MCP Server

New MCP Servers

MCP directory API

Markdown (`.md`) - Human-Readable

JSON (`.json`) - Structured Data

YAML (`.yml`) - Configuration-Friendly