Use Planet Roadmap with Claude

The @planetroadmap/mcp package is a Model Context Protocol (MCP) server that lets Claude Code, Claude Desktop, and other MCP-compatible clients read and update your tasks, projects, feature requests, and OKRs. Once connected, you can say things like “plan my week,” “triage open feedback,” or “mark the billing task done” and Claude will use the API on your behalf.

Requires: a Pro or Enterprise plan (API access), Node.js 18+ on the machine running Claude, and an MCP-compatible client.

1. Generate an API key

Go to Settings → Integrations in your dashboard and click Create API Key. Grant the permissions you want Claude to have. A reasonable default for full read/write is:

tasks:read, tasks:write
projects:read
requests:read, requests:write
comments:read, comments:write
okrs:read, okrs:write

Copy the key when it's revealed — you won't be able to see it again. The reveal dialog also shows a ready-to-paste config block (see step 2).

2. Add it to your Claude config

Claude Code

Edit ~/.claude/mcp.json (create it if it doesn't exist). For a project-scoped install, use .claude/mcp.json in the project root instead.

~/.claude/mcp.json

{
  "mcpServers": {
    "planetroadmap": {
      "command": "npx",
      "args": ["-y", "@planetroadmap/mcp"],
      "env": {
        "PLANETROADMAP_API_KEY": "pk_live_your_api_key",
        "PLANETROADMAP_ORG_SLUG": "your-org-slug"
      }
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Use the same shape as above. Restart Claude Desktop after saving.

Other clients (Cursor, Zed, etc.)

Any MCP client that accepts a stdio server entry will work. Use the same command + args + env values, dropped into whatever config block your client expects.

3. (Optional) Install the skill

The package ships a Claude skill that teaches Claude Planet Roadmap's vocabulary (task vs feature request vs portal), common workflows (planning, triage, OKR check-ins), and conventions (which fields are public, what not to delete). It's optional — the MCP server works without it — but Claude is noticeably better with it loaded.

Install the skill globally

mkdir -p ~/.claude/skills/planetroadmap
cp node_modules/@planetroadmap/mcp/skill/SKILL.md \
   ~/.claude/skills/planetroadmap/

If you ran npx -y @planetroadmap/mcp from the config and never installed locally, you can grab the file directly from the unpacked tarball: npm pack @planetroadmap/mcp and extract skill/SKILL.md.

4. Try it

Restart your Claude client so it picks up the new server. Then try any of these:

“Use planetroadmap to show me my open tasks, sorted by priority.”
“What feature requests have the most votes right now?”
“Mark the ‘dark mode’ task as done.”
“Move the API auth feedback to planned with a note that we're shipping in Q3.”
“How are we tracking against this quarter's OKRs?”

Available tools

The MCP server exposes 16 tools. Claude picks which ones to call based on what you ask for — you usually don't need to name them.

Tool	What it does	Permission
whoami	Verify the key, show org & granted permissions	—
list_tasks	Filter tasks by status, project, assignee, search, since	tasks:read
get_task	Full details of one task	tasks:read
create_task	Create a task (assignee resolved by email)	tasks:write
update_task	Patch any subset of task fields	tasks:write
delete_task	Hard delete (prefer status=done)	tasks:write
list_projects	Filter projects by status, search	projects:read
get_project	Project detail with task count	projects:read
list_feature_requests	Customer feedback, filter by status, search, votes	requests:read
get_feature_request	One feature request	requests:read
create_feature_request	Log feedback into a portal	requests:write
update_feature_request	Triage — change status, statusNote, move portals	requests:write
list_comments	Comments on feature requests	comments:read
add_comment	Post a public, official-by-default reply	comments:write
list_okrs	Objectives with key results and computed progress	okrs:read
update_key_result_progress	Bump currentValue on a key result	okrs:write

Environment variables

Variable	Required	Default	Notes
PLANETROADMAP_API_KEY	yes	—	From Settings → Integrations
PLANETROADMAP_ORG_SLUG	yes	—	The slug in your dashboard URLs
PLANETROADMAP_BASE_URL	no	https://planetroadmap.com	Override for staging or self-hosted

Troubleshooting

Claude doesn't see the tools

Restart your client after editing the MCP config — most clients only read it on startup. In Claude Code, run /mcp to list connected servers; planetroadmap should appear with 16 tools.

`401 Invalid API key`

The key is wrong or has been deleted. Generate a new one in Settings → Integrations and update the PLANETROADMAP_API_KEY env var in your config.

`403 Organization mismatch`

PLANETROADMAP_ORG_SLUG doesn't match the org the key belongs to. Check the slug in your dashboard URL.

`403 Missing X permission`

The key wasn't granted that scope. Permissions can't be edited after creation — create a new key with the missing permission and swap it in.

`403 API access requires a Pro or Enterprise plan`

The org is on the free plan. Upgrade in billing settings to enable API access.

`429` rate limited

Each API key is capped at 100 requests per minute. Slow down or split work across keys. See Rate Limits for details.

Security notes

API keys grant Claude the same permissions you check on creation. If you don't want Claude to be able to delete tasks or post public comments, simply don't grant tasks:write or comments:write.
Keys are stored in your local Claude config file in plaintext. Treat that file like an SSH key — don't commit it to a repo.
Comments and feature-request statusNote fields are public — visible to anyone on your portal. Review what Claude is about to post before approving the tool call.
You can revoke a key at any time from Settings → Integrations. Claude will get 401 on its next call.

Source & issues: The package is open source on npm. Found a bug? Open an issue in the main repo.