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
• 🚀 Quick Start
• 🤖 AI Integration Tips
• 🔧 Installation Examples
• 📁 Supported File Formats
• 🛠️ Available Tools
• 🎛️ Environment Variables
• 📊 File Formats
• 🖥️ Server Usage
• 💻 CLI Usage
• 🧪 Development
• 🛠️ Troubleshooting
• Why not let AI edit files directly?
• 🤝 Contributing
• 📄 License
• 🔗 Links

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

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