Which integrations are available for this server?

Provides task management functionality through a Docker container, allowing deployment of the MCP server in containerized environments. Supports task management in Markdown files with automatic formatting of task lists, including statuses and checkboxes. Requires Node.js ≥20 for running the MCP server, with full support for Node.js environments. Available as an npm package for easy installation and integration into Node.js projects. Offers full TypeScript support with Zod validation for type-safe task management operations. Allows managing tasks in YAML format, providing configuration-friendly representation for task data. Uses Zod for runtime type validation of task data, ensuring data integrity and type safety.

How do I use MCP Tasks?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Tasks add 'review quarterly report' to my tasks" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Tasks 📋

Install MCP Server npm version Node.js License: MIT Docker

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

Related MCP server: Calculator MCP Server

✨ 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.

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

Resources

Looking for Admin?

Tools

Latest Blog Posts

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

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

Markdown (`.md`) - Human-Readable

JSON (`.json`) - Structured Data

YAML (`.yml`) - Configuration-Friendly