# powerplan [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/CynaCons/powerplan  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/powerplan

## Description
MCP server that makes PLAN.md the operational backbone of agentic development

## Tools
Capabilities this server exposes over MCP:

- **create_plan** — Bootstrap `./PLAN.md` (or `plan_path`) when missing; `force` to overwrite
- **show_miniplan** — Session opener** — raw PLAN.md snippet: the current (or named) iteration byte-for-byte, neighbours collapsed to header lines (`before`/`after`)
- **get_current_iteration** — Preferred for agents** — scoped JSON for current work
- **get_iteration** — JSON for one version (tasks, progress)
- **list_iterations** — Navigate without full-file reads
- **create_major** — Surgical mutations (batch add in one write)
- **complete_task** — One or many (`indexes` / `tasks`); optional `[agent: id]
- **start_iteration** — ACTIVE/current vs COMPLETE lifecycle
- **check_plan** — Structure lint
- **show_plan** — Compact human skim (not a full dump)

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "powerplan": {
    "command": "uvx",
    "args": ["powerplan-mcp"]
  }
}
```

## Documentation

## 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:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/powerplan/readme_