Powerplan

What powerplan does

The powerplan MCP server turns a project’s PLAN.md into an MCP-accessible planning interface. It is intended for coordinator and worker agents that need to inspect current work, update tasks, and keep iteration status consistent while avoiding unrestricted file edits.

The managed format recognizes major versions such as ## vX.Y — Title, iterations such as ### vX.Y.Z — Title, a goal line, checkbox tasks, and a backlog section. Other phase-like headings and prose are preserved as opaque content. The server can also add optional trailing [agent: id] markers to lines changed by mutations.

Use it when PLAN.md is the shared operational record for a project or agent group. It can be paired with PowerSpawn, although the README specifies that the two MCP servers remain separately registered and do not merge.

How it works

The server communicates over MCP using stdio. By default, tools walk upward from the current working directory to find the nearest PLAN.md. Each tool also accepts an optional relative or absolute plan_path, allowing callers to select a different file.

A typical agent session starts with show_miniplan, which returns the active or selected iteration byte-for-byte while reducing neighboring iterations to header lines. get_current_iteration provides the preferred scoped JSON representation for agents, and get_iteration returns tasks and progress for one version. Navigation tools such as list_iterations, find_task, and get_backlog avoid requiring a full-file read.

Mutations are performed through dedicated operations rather than freeform file replacement. The server writes changes surgically and can batch task additions or completions. check_plan checks plan structure, while show_plan and show_current_iteration provide compact human-oriented views.

Setup and configuration

Install with uv and run the stdio server using:

uvx powerplan-mcp

The package requires uv, which provides uvx, or Python 3.10 or newer. Without uv, install the PyPI package with pip install powerplan-mcp, then launch it with python -m powerplan.

Clients can register the process with the powerplan-mcp command and pass PYTHONIOENCODING=utf-8 and PYTHONUNBUFFERED=1 in the environment, as shown in the README examples. Explicit configurations are provided for Claude Code, Cursor, Claude Desktop, and Grok. A source checkout can be installed in editable mode with pip install -e ".[dev]", run with python -m powerplan, or started directly through powerplan_server.py.

Tools and capabilities

The powerplan MCP server includes tools for:

• Creating PLAN.md when it is absent, with an optional overwrite force.
• Showing the current or named iteration in compact raw or JSON forms.
• Listing iterations, locating tasks, and retrieving backlog content.
• Creating majors or iterations and adding one or multiple tasks.
• Completing, reopening, removing, or deferring one or multiple tasks.
• Starting and closing iterations to represent ACTIVE/current and COMPLETE states.
• Checking plan structure and producing compact plan summaries.

complete_task accepts indexes or task selections, and task mutations can include an agent identifier. If a tool reports that PLAN.md is missing, create the file first with create_plan.

Limitations and notes

The server is focused on PLAN.md rather than general project-file editing. show_miniplan is designed as a session opener, and show_plan is a compact human skim; neither is described as a complete file dump. The README also advises agents not to read all of PLAN.md just to determine their next action.

The default path behavior depends on the process working directory, so callers operating outside the project tree should pass plan_path. A force-enabled create_plan can overwrite an existing plan, so it should be used deliberately. The published package name is powerplan-mcp; powerplan on PyPI refers to an unrelated package.