# plane-mcp

An MCP (Model Context Protocol) server for [Plane](https://github.com/makeplane/plane), the open-source project management tool — plus a setup wizard that binds a project folder to a Plane project in one command.

One CLI, four subcommands:

- `plane-mcp` (or `plane-mcp setup`) — interactively binds the current folder to a
  Plane project (writes MCP config for Claude Code / Codex, updates the agent memo).
- `plane-mcp mcp` — the MCP server itself (stdio).
- `plane-mcp list` — lists projects from your local registry.
- `plane-mcp update` — self-upgrade via pipx.

## Design

Most Plane MCP servers expose dozens of tools and make the model pass
`workspace` and `project` on every call. This one is deliberately narrow:
**one MCP server instance = one Plane project**, fixed via environment
variables at startup. The model gets a small, task-focused tool surface and
can never write to the wrong project.

## Tools (MCP)

| Tool | Purpose |
|---|---|
| `list_tasks(status_group?, state_id?, assignee_id?, limit?, cursor?)` | List tasks; `status_group=backlog` shows only the backlog. |
| `get_task(id_or_identifier)` | By UUID or `PROJ-42` identifier. |
| `create_task(name, …)` | Create a task. |
| `update_task(issue_id, …)` | Patch any fields. |
| `change_status(issue_id, status_group OR state_id)` | Sugar over update. |
| `add_comment(issue_id, body_html)` | Post an HTML comment (sanitized via nh3). |
| `list_comments(issue_id)` | Read comments, incl. presigned URLs for inline images. |
| `add_comment_with_image(issue_id, body_html, image_path)` | Comment with an embedded image. |
| `upload_attachment(issue_id, file_path)` | Attach a local file. |
| `list_attachments(issue_id)` / `get_attachment_url(…)` / `delete_attachment(…)` | Manage attachments. |
| `read_attachment_image(issue_id, attachment_id)` | Return an image attachment as native MCP image content. |
| `list_states()` / `list_members()` / `list_labels()` | Lookups, cached 5 min. |

`status_group` ∈ `backlog`, `unstarted`, `started`, `completed`, `cancelled`.

## Installation

```bash
brew install pipx       # or: sudo apt install pipx
pipx ensurepath

pipx install git+https://github.com/babazulu/plane-mcp
```

## Configure your projects

Create `~/.config/plane-mcp/projects.toml` with one entry per Plane project
you work with:

```toml
[projects.MyProject]
id = "00000000-0000-0000-0000-000000000000"   # Plane project UUID
api_key = "plane_api_..."                     # Plane API key (Workspace Settings → API tokens)
workspace_slug = "my-workspace"
base_url = "https://plane.example.com"        # your Plane host (or https://app.plane.so)
```

Verify with:

```bash
plane-mcp list
```

## Bind a project folder

```bash
cd /path/to/my/project
plane-mcp                           # interactive: pick the agent and the Plane project
```

Or fully flag-driven:

```bash
plane-mcp setup --agent codex --project MyProject
plane-mcp setup --agent claude --project MyProject --dir /other/path
```

What it does:

1. Creates/merges `./.mcp.json` (Claude Code) or `./.codex/config.toml`
   (Codex) — adds or updates the `plane-<name>` MCP server entry and
   **leaves existing entries untouched**.
2. Upserts an agent memo block in `CLAUDE.md` (Claude) or `AGENTS.md`
   (Codex), bounded by `<!-- plane-mcp:start --> … end -->` markers.
3. Prints a first prompt to copy into the agent.

On the next launch in that folder, Claude Code or Codex picks up the
`plane-<name>` MCP server and can work with tasks.

## MCP server configuration (ENV)

The MCP host (Claude Code / Codex) passes these from its config. If you run
`plane-mcp mcp` by hand, set them yourself:

```
PLANE_API_URL=https://plane.example.com
PLANE_API_KEY=...
PLANE_WORKSPACE_SLUG=...
PLANE_PROJECT_ID=<uuid>
```

## Development

```bash
git clone https://github.com/babazulu/plane-mcp
cd plane-mcp
python3 -m venv .venv && . .venv/bin/activate
pip install -e .

plane-mcp list
plane-mcp setup --dir /tmp/test-folder --agent codex --project MyProject
```

## Releases

1. Bump `version` in `pyproject.toml` and `src/plane_mcp/__init__.py`.
2. Commit and push (CI runs lint + build).
3. Tag: `git tag v0.2.0 && git push --tags` — CI attaches the wheel and sdist
   to a GitHub Release.

## Troubleshooting

**`plane-mcp: missing required env vars`** — the MCP host didn't pass the
`PLANE_*` variables. Re-run `plane-mcp setup` in the folder, or check the
`env` block in `.mcp.json` / `.codex/config.toml`.

**`no project registry found`** — create `~/.config/plane-mcp/projects.toml`
(see [Configure your projects](#configure-your-projects)).

**The agent doesn't see the MCP server** — make sure `plane-mcp` is on
`PATH` for the process that spawns the agent, and that the config file sits
in the folder you launched the agent from:

```bash
which plane-mcp             # should print a path
plane-mcp mcp < /dev/null   # should fail fast with a readable env-var error
```

## License

[MIT](LICENSE)