Task Manager MCP

A Model Context Protocol (MCP) server for task management with dependency resolution. Stores tasks as markdown files in an Obsidian vault, lets you queue work, assign tasks to your agent, and have any MCP-capable agent (Claude Code, Cursor, Cline, Continue, Goose, Windsurf, …) pick up the next workable task automatically.

Install via your agent (easiest)

Open your MCP-capable agent (Claude Code, Cursor, Cline, …), paste:

Read this and help me install it: https://github.com/punparin/task-manager-mcp/blob/main/INSTALLATION.md

The agent will walk you through it — picking Docker vs Python, vault path, tasks folder, actor list, scope — and ask before assuming anything. See INSTALLATION.md for the full guide.

Quickstart (manual)

# 1. Pull the image
docker pull ghcr.io/punparin/task-manager-mcp:latest

# 2. Register with your MCP client (Claude Code shown — see
#    docs/configuration.md for other clients).
claude mcp add -s user task-manager -- \
  docker run -i --rm \
    -v /path/to/your/vault:/vault \
    ghcr.io/punparin/task-manager-mcp:latest

Then in your agent, try:

create task "First demo task" P2 assignee:agent
next_task

The first call writes T-001.md into <vault>/tasks/; the second returns it because nothing's blocking it. Mark it Done with complete_task T-001 and the agent will tell you what's now unblocked.

Want a Kanban board for the same tasks? Run the Explorer sidecar.

What it does

• Dependency resolution — next_task returns tasks whose blockers are all Done
• Priority + due date sorting — P1s first, then by due date
• Cycle detection — prevents impossible task graphs
• Status workflow — Backlog → Ready → In Progress → Done (with Blocked / Cancelled escapes)
• Auto-promote on unblock — when you complete a task, Backlog dependents whose last blocker just cleared flip to Ready in place, and the agent tells you exactly what opened up
• Body-as-truth for checklists and comments — edits in Obsidian and tool calls from your agent never drift apart
• Append-only audit log — every status transition is recorded in <vault>/.task-manager/audit.jsonl with last_status_change mirrored into frontmatter for cheap recency filtering

See docs/tools.md for the full 18-tool reference.

Documentation

• docs/architecture.md — diagrams, status state machine, dependency-resolution algorithm, module layout
• docs/tools.md — every MCP tool, grouped by role
• docs/task-format.md — frontmatter schema, comment thread, checklist progress
• docs/configuration.md — vault path, custom tasks folder, custom actors, MCP client registration
• docs/explorer.md — Kanban + dep graph web UI, REST endpoints
• INSTALLATION.md — agent-driven install guide

The agent operating rules ship with the server via MCP initialize.instructions — canonical source is task_manager_mcp/agent_instructions.py. Most MCP clients (Claude Code, …) inject them into the agent's system prompt automatically; nothing to paste.

Contributing

See CONTRIBUTING.md for dev setup and the bar for PRs.