plane-mcp

An MCP (Model Context Protocol) server for 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

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:

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

plane-mcp list

Bind a project folder

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

Or fully flag-driven:

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

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).

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:

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

License

MIT