mcp-task-manager

README

MCP Task Manager

A Go-based MCP (Model Context Protocol) server for task management, designed for Claude and coding agents.

Overview

MCP Task Manager provides a simple but powerful task management system that integrates with AI coding assistants via the Model Context Protocol. Tasks are stored as human-readable Markdown files with YAML frontmatter, making them easy to version control and inspect.

Features

• Markdown-based storage - Tasks stored as .md files with YAML frontmatter
• Priority-based workflow - Critical > High > Medium > Low, with oldest-first tiebreaker
• Agent-friendly tools - get_next_task, start_task, complete_task for automated workflows
• Self-healing index - JSON index cache rebuilds automatically from source files
• Configurable task types - Default: feature, bug; extensible via config

Installation

Prerequisites

• Go 1.21 or later

Install with Go

go install github.com/gpayer/mcp-task-manager/cmd/mcp-task-manager@latest

Download Pre-built Binaries

Download the latest release for your platform from the Releases page:

• mcp-task-manager-linux-amd64 - Linux (x86_64)
• mcp-task-manager-linux-arm64 - Linux (ARM64)
• mcp-task-manager-windows-amd64.exe - Windows (x86_64)

After downloading, rename and make executable (Linux/macOS):

mv mcp-task-manager-linux-amd64 mcp-task-manager
chmod +x mcp-task-manager
# Optionally move to a directory in your PATH:
sudo mv mcp-task-manager /usr/local/bin/

Build from Source

git clone https://github.com/gpayer/mcp-task-manager.git
cd mcp-task-manager
go build -o mcp-task-manager ./cmd/mcp-task-manager

Usage

Running the Server

The MCP server communicates via stdio:

mcp-task-manager

CLI Usage

The same binary also works as a standalone CLI tool when called with arguments:

# List all tasks
mcp-task-manager list
mcp-task-manager list --status=todo --priority=high
mcp-task-manager list --json

# Get task details
mcp-task-manager get 1
mcp-task-manager get 1 --json

# Create a task
mcp-task-manager create "Fix login bug" -p high -t bug -d "Users can't log in"

# Update a task
mcp-task-manager update 1 --title "New title" -s in_progress

# Delete a task
mcp-task-manager delete 1

# Workflow commands
mcp-task-manager next              # Get highest priority todo task
mcp-task-manager start 1           # Start a task (todo -> in_progress)
mcp-task-manager complete 1        # Complete a task (in_progress -> done)

# Other
mcp-task-manager version
mcp-task-manager --help

CLI Commands

Command	Description
list	List tasks with optional filters (-s status, -p priority, -t type, where allowed task types depend on config and default to feature, bug)
get <id>	Get task details by ID
create <title>	Create task (defaults: priority=medium, type=first configured task type; with default config that is feature; allowed task types depend on config and default to feature, bug); use --parent for subtasks
update <id>	Update task fields, including type (allowed task types depend on config and default to feature, bug)
delete <id>	Delete a task
next	Get highest priority todo task
start <id>	Move task to in_progress
complete <id>	Move task to done
version	Show version

All commands support --json / -j for JSON output.

Claude Desktop Integration

Add to your Claude Desktop configuration (~/.config/claude/claude_desktop_config.json on Linux, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "task-manager": {
      "command": "/path/to/mcp-task-manager"
    }
  }
}

Claude Code Integration

MCP Task Manager includes a plugin for Claude Code that enables automated task execution with the superpowers plugin.

Setup:

1. Add the MCP server:

claude mcp add --transport stdio task-manager -- mcp-task-manager

1. Install the plugin (includes the superpowers-workflow skill):

# Add the marketplace
/plugin marketplace add gpayer/mcp-task-manager

# Install the plugin
/plugin install mcp-task-manager@mcp-task-manager

Usage:

Use the /mcp-task-manager:superpowers-workflow skill to automatically execute pending tasks with the repo-local planner, coder, and reviewer agents. If one of those agents cannot be used, the workflow stops and asks before allowing a fallback.

Codex Integration

Add the MCP server:

codex mcp add task-manager -- mcp-task-manager

Paste into Codex to install the skills and agents:

Fetch https://raw.githubusercontent.com/gpayer/mcp-task-manager/main/.codex/INSTALL.md and execute the installation steps exactly.

Usage:

Use the $superpowers-workflow skill to automatically execute pending tasks with the repo-local planner, coder, and reviewer agents. If one of those agents cannot be used, the workflow stops and asks before allowing a fallback.

MCP Tools

Task Management

Tool	Description
create_task	Create a new task with title, description, priority, type, and optional parent_id for subtasks. Allowed task type values come from config and default to feature, bug.
update_task	Modify task fields (title, description, status, priority, type). Allowed task type values come from config and default to feature, bug.
list_tasks	List tasks with optional filters (status, priority, type); use parent_id filter for subtasks. Allowed task type values come from config and default to feature, bug.
get_task	Get full details of a task by ID (includes subtasks for parent tasks)
delete_task	Remove a task; use delete_subtasks to cascade

Agent Workflow

Tool	Description
get_next_task	Returns highest priority todo task
start_task	Move task from todo to in_progress
complete_task	Move task from in_progress to done

Relations

Tool	Description
add_relation	Add a relation between two tasks. Allowed relation type values come from config and default to blocked_by, relates_to, duplicate_of.
remove_relation	Remove a relation between two tasks. Allowed relation type values come from config and default to blocked_by, relates_to, duplicate_of.

Configuration

Config File

Create mcp-tasks.yaml in the working directory:

task_types:
  - feature
  - bug
  - chore
  - docs
relation_types:
  - blocked_by
  - relates_to
  - duplicate_of

The task_types list defines the allowed values for every task type field in the CLI, MCP tools, and task frontmatter. If omitted, the default allowed values are feature and bug. The relation_types list defines the allowed values for every relation type field in MCP tools and task metadata. If omitted, the default allowed values are blocked_by, relates_to, and duplicate_of.

Environment Variables

Variable	Description	Default
MCP_TASKS_DIR	Directory for task storage	./tasks

Task Format

Tasks are stored as Markdown files with YAML frontmatter:

---
id: 1
title: "Implement user authentication"
status: todo
priority: high
type: feature
created_at: 2025-01-15T10:30:00Z
updated_at: 2025-01-15T10:30:00Z
---

Detailed description in Markdown format.

- Acceptance criteria
- Implementation notes
- Links and references

The type field must be one of the configured task_types values. With the default configuration, allowed values are feature and bug.

Status Values

• todo - Task is pending
• in_progress - Task is actively being worked on
• done - Task is completed

Priority Levels

• critical - Highest priority
• high - Important tasks
• medium - Normal priority (default)
• low - Can wait

Subtasks

Tasks support single-level nesting via the parent_id field.

Creating subtasks:

# CLI
mcp-task-manager create "Implement login form" -p high --parent 1

# MCP tool
create_task with parent_id parameter

Automatic behaviors:

• Starting a subtask auto-starts its parent task
• Completing the last subtask auto-completes the parent
• Parent tasks cannot be completed while subtasks remain incomplete
• get_next_task returns subtasks instead of parents with incomplete subtasks

Project Structure

mcp-task-manager/
├── cmd/mcp-task-manager/    # Entry point (MCP server + CLI)
├── internal/
│   ├── cli/                 # CLI command handlers
│   ├── config/              # Configuration loading
│   ├── storage/             # Markdown + index storage
│   ├── task/                # Task model and service
│   └── tools/               # MCP tool handlers
├── tasks/                   # Task storage (created at runtime)
├── mcp-tasks.yaml           # Configuration file
└── CLAUDE.md                # AI assistant instructions

License

MIT License - see LICENSE file for details.