mcp-tasks

mcp-tasks is an efficient multi-file task manager that can operate across multiple task files in Markdown, JSON, and YAML formats. It provides a compact set of tools designed to minimize AI prompt complexity while offering powerful search, filtering, and organization capabilities. The available tools include tasks_setup for initializing a task file, tasks_search for filtering tasks, tasks_add for creating new tasks, tasks_update for changing task statuses, and tasks_summary for an overview of counts and work-in-progress. When PREFIX_TOOLS is enabled, tool commands are prefixed with tasks_ (for example, tasks_setup and tasks_add). Use these tools to manage your tasks within a single file or across several files, with IDs and 4-character IDs used to reference tasks and sources. The server is designed to prevent unintended edits, while still allowing AI-assisted management and optional Reminders sections for ongoing prompts.

To use mcp-tasks in your workflow, start it via NPX (recommended) or Docker, then address the task file with the appropriate tool calls. For example, initialize a task file with tasks_setup, add tasks with tasks_add, search with tasks_search, and update statuses with tasks_update. You can also retrieve a quick overview with tasks_summary. When running in a hosted or remote setup, you can expose the server over HTTP/streaming if you enable the transport option, enabling remote interactions via a URL like http://localhost:4680/mcp.

Prerequisites:

• Node.js (recommended: current LTS) and npm installed on your system
• Optional: Docker if you prefer running via container

Installation steps (NPX installation, no global install required):

1. Ensure Node.js and npm are installed. You can verify with:

node -v
npm -v

2. Run the MCP server using NPX (recommended):

npx -y mcp-tasks

This pulls the mcp-tasks package and starts the server, exposing the MCP interface for your editors and tools.

Alternative Docker method:

1. Pull and run the image:

docker run --rm -i flesler/mcp-tasks

2. If you need to customize ports or transport, adjust the command accordingly or follow the full configuration example in the README.

Note: If you plan to use HTTP transport for remote access, you can start with environment variables and a transport flag, e.g. TRANSPORT=http PORT=4680 npx mcp-tasks, as described in the installation examples of the README.

Tips and common notes:

• Supports multiple file formats: Markdown (.md), JSON (.json), YAML (.yml). The format is auto-detected by file extension.
• Status workflow is customizable via environment variables in the full config example (STATUS_WIP, STATUS_TODO, STATUS_DONE, etc.).
• By default, tools can be prefixed with tasks_ when PREFIX_TOOLS=true, making the commands explicit (e.g., tasks_setup, tasks_add).
• To avoid conflicting edits by AI, consider using the CLI in a separate terminal for adding tasks (e.g., npx mcp-tasks add "Your task" "To Do" 0).
• When exposing the server remotely, you can choose HTTP transport to enable remote access, but ensure you manage access and security appropriately.
• Each task and source uses a 4-character alphanumeric ID, which is important for operations like tasks_search and tasks_update.