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
• 🚀 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

## R

---

*README truncated. [View full README on GitHub](https://github.com/flesler/mcp-tasks).*