MCP Tasks

You use this MCP server to manage tasks across multiple formats with smart filtering, real-time persistence, and safe AI collaboration. It keeps your task state organized, prevents duplicates, and lets you control how the AI handles work-in-progress tasks while supporting Markdown, JSON, and YAML task files.

How to use

Connect your MCP client and start sending task commands. You can set up a dedicated task file for your project, then add, search, and update tasks without large context switches. Use the client to track work in progress, move tasks between statuses, and see a live overview of your task counts. The AI can be guided to work with your task file through prompts like Use mcp-tasks tools to track our work in path/to/tasks.md and append use mcp-tasks to ongoing prompts for updates.

How to install

Prerequisites: install Node.js version 20 or higher on your machine.

Option A: NPX (recommended) Start by adding a MCP server entry to your client configuration:

{
  "mcpServers": {
    "mcp-tasks": {
      "command": "npx",
      "args": ["-y", "mcp-tasks"]
    }
  }
}

Option B: Docker Run (no local Node install required for the server):

{
  "mcpServers": {
    "mcp-tasks": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "flesler/mcp-tasks"
      ]
    }
  }
}

Configuration and usage tips

When you configure the server, you can enable a full range of environment variables to tailor behavior, including status names, WIP rules, and transport options. The server can be used in standard input/output (stdio) mode for local runs or via HTTP transport if you expose it remotely.

Environment variables

You can customize how the server runs by setting environment variables. Example values are shown below, but you can adjust them to fit your workflow.

{
  "env": {
    "TRANSPORT": "stdio",
    "PORT": "4680",
    "PREFIX_TOOLS": "true",
    "STATUS_WIP": "In Progress",
    "STATUS_TODO": "To Do",
    "STATUS_DONE": "Done",
    "STATUS_REMINDERS": "Reminders",
    "STATUS_NOTES": "Notes",
    "STATUSES": "Backlog",
    "AUTO_WIP": "true",
    "KEEP_DELETED": "true",
    "INSTRUCTIONS": "Use mcp-tasks tools when the user mentions new or updated tasks",
    "SOURCES_PATH": "./sources.json",
    "DEBUG": "false"
  }
}

Server usage

You can run the server locally in stdio mode or expose it over HTTP. For stdio, simply start the server with your chosen command. For HTTP, set TRANSPORT=http and provide a port, then point your client to the generated HTTP endpoint.

# 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 use mcp-tasks directly from the command line for quick management. This mirrors the capabilities exposed by the MCP server: setup a file, add tasks, search, update statuses, or get a summary.

# Setup a task file
mcp-tasks setup tasks.md $PWD

# Add tasks
mcp-tasks add "Implement authentication" 
#mcp-tasks add "Write tests" "Backlog"
mcp-tasks add "Fix critical bug" "In Progress" 0

# Search tasks
mcp-tasks search
mcp-tasks search "" "auth,login"
mcp-tasks search "To Do,Done" ""
mcp-tasks search "In Progress" "bug"

# 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

Supported file formats

The MCP server supports Markdown (.md), JSON (.json), and YAML (.yml) task files. Each format is auto-detected by extension and can be used within the same project.

File formats are crafted to preserve a consistent workflow, including sections like In Progress, To Do, Backlog, Done, Reminders, and Notes in Markdown, or equivalent groupings in JSON/YAML.

Available tools

tasks_setup

Initialize a task file (creates if missing, supports .md, .json, .yml) and returns a source reference and initial counts.

tasks_search

Search tasks with filtering by terms, statuses, and IDs to return matching tasks.

tasks_add

Add new tasks to a given status with optional index position; returns updated source and tasks.

tasks_update

Update tasks by IDs to a new status or delete, returning the updated view.

tasks_summary

Get an overview of counts per status and the current in-progress list.