MCP Tasks

What is MCP Tasks?

MCP Tasks is a Model Context Protocol server for task management, designed to work with Claude, Cursor, and other MCP clients. It minimizes tool confusion and maximizes LLM budget efficiency by providing only five tools, batch operations, and smart defaults. It supports Markdown, JSON, and YAML task files and offers powerful search, filtering, and organization capabilities.

How to use MCP Tasks?

Install via npx (npx -y mcp-tasks) or Docker (docker run --rm -i flesler/mcp-tasks). Add the configuration to your MCP client (e.g., Cursor's mcp.json or Claude Desktop's claude_desktop_config.json). The server provides five tools: tasks_setup, tasks_search, tasks_add, tasks_update, and tasks_summary. Use environment variables to customize workflow statuses, transport mode, auto-WIP behavior, and more. A CLI is also available for quick task management without an AI client.

Key features of MCP Tasks

• Ultra‑efficient design with only five tools to reduce AI confusion
• Budget‑optimized with batch operations and smart defaults
• Multi‑format support: Markdown, JSON, and YAML task files
• Powerful case‑insensitive text/status filtering with OR logic
• Auto‑WIP management that automatically limits work in progress
• Ultra‑safe: AI cannot rewrite or delete tasks without explicit configuration

Use cases of MCP Tasks

• Track project tasks and subtasks in a human-readable Markdown file
• Manage customizable workflow states (To Do, In Progress, Done, etc.)
• Integrate task management directly into AI-assisted coding sessions
• Quickly add, search, and update tasks via CLI without interrupting AI operations
• Maintain a structured task list that persists across sessions and tools

FAQ from MCP Tasks

What file formats does MCP Tasks support?

Markdown (.md), JSON (.json), and YAML (.yml) are supported. The format is auto‑detected from the file extension. Markdown is recommended for human readability.

How does auto‑WIP management work?

When AUTO_WIP is enabled (default), if a task is moved to the WIP status, all other WIP tasks are moved to To Do. If no WIP task exists, the first To Do task is moved to WIP. This can be disabled by setting AUTO_WIP=false.

Can the AI delete my tasks?

By default, AI tools can only add and move tasks; they cannot rewrite or delete them. Deletion can be enabled through configuration (e.g., setting KEEP_DELETED=false or allowing the tasks_update tool to use the “Deleted” status).

What transport modes are available?

The server supports stdio (default) and http transport. Set the TRANSPORT environment variable to http and optionally change the PORT (default 4680) for remote access.

How do I add tasks manually while the AI is working?

Use the CLI from a separate terminal: npx mcp-tasks add "Your task text" "To Do" 0. This safely adds tasks without interfering with the AI’s use of the tools.