ProductPlan MCP Server

ProductPlan MCP Server

[CI] [lint] [CodeScene Average Code Health]

Talk to your roadmaps using AI. Ask questions, create ideas, check OKR progress, and manage launches through natural conversation with Claude, Cursor, or other AI assistants.

What can you do with this?

Instead of clicking through ProductPlan's interface, just ask:

"What's on our Q1 roadmap?"

"Show me all objectives that are behind schedule"

"Create a new idea for mobile app improvements"

"What launches are coming up this month?"

"List all ideas tagged 'customer-request'"

"Color every eFormidling bar with the Customer satisfaction legend"

"Move these ten bars to the Platform lane and tag them Q3"

The AI fetches your real ProductPlan data and responds in seconds. Changes to many bars go through one validated call: every bar is checked before anything is written, and you can ask for a dry run first.

Who is this for?

• Product Managers who want faster access to roadmap data
• Team leads who need quick status updates without context-switching
• Anyone using AI assistants (Claude, Cursor, etc.) who wants ProductPlan integrated into their workflow

No coding required. You'll copy a file and paste some settings.

Quick start (5 minutes)

Step 1: Get your ProductPlan API token

1. Log into ProductPlan
2. Go to Settings → API (or visit this link directly)
3. Copy your API token

Step 2: Download the app

Go to the Releases page and download the right file for your computer:

On Mac/Linux, open Terminal and run these two commands (replace the filename with what you downloaded):

chmod +x ~/Downloads/productplan-darwin-arm64sudo mv ~/Downloads/productplan-darwin-arm64 /usr/local/bin/productplan

You'll be asked for your password. This is normal.

On Windows:

1. Create a folder for the binary (if it doesn't exist):

   mkdir C:\Tools

2. Move the downloaded .exe to that folder and rename it:

   move %USERPROFILE%\Downloads\productplan-windows-amd64.exe C:\Tools\productplan.exe

3. Use the full path C:\Tools\productplan.exe in your AI assistant config (shown in Step 3)

Note: You can skip adding to PATH. Just use the full file path in your configuration.

Step 3: Connect to your AI assistant

Pick the tool you use:

{  "mcpServers": {    "productplan": {      "command": "/usr/local/bin/productplan",      "env": {        "PRODUCTPLAN_API_TOKEN": "your-token"      }    }  }}

{  "mcpServers": {    "productplan": {      "command": "C:\\Tools\\productplan.exe",      "env": {        "PRODUCTPLAN_API_TOKEN": "your-token"      }    }  }}

{  "mcpServers": {    "productplan": {      "command": "/usr/local/bin/productplan",      "env": {        "PRODUCTPLAN_API_TOKEN": "your-token"      }    }  }}

{  "mcpServers": {    "productplan": {      "command": "C:\\Tools\\productplan.exe",      "env": {        "PRODUCTPLAN_API_TOKEN": "your-token"      }    }  }}

{  "productplan": {    "command": "/usr/local/bin/productplan",    "env": {      "PRODUCTPLAN_API_TOKEN": "your-token"    }  }}

{  "productplan": {    "command": "C:\\Tools\\productplan.exe",    "env": {      "PRODUCTPLAN_API_TOKEN": "your-token"    }  }}

{  "cline.mcpServers": {    "productplan": {      "command": "/usr/local/bin/productplan",      "env": {        "PRODUCTPLAN_API_TOKEN": "your-token"      }    }  }}

{  "cline.mcpServers": {    "productplan": {      "command": "C:\\Tools\\productplan.exe",      "env": {        "PRODUCTPLAN_API_TOKEN": "your-token"      }    }  }}

{  "mcpServers": [    {      "name": "productplan",      "command": "/usr/local/bin/productplan",      "env": {        "PRODUCTPLAN_API_TOKEN": "your-token"      }    }  ]}

{  "mcpServers": [    {      "name": "productplan",      "command": "C:\\Tools\\productplan.exe",      "env": {        "PRODUCTPLAN_API_TOKEN": "your-token"      }    }  ]}

Step 4: Start asking questions

Open your AI assistant and try:

• "List my ProductPlan roadmaps"
• "What bars are on roadmap [name]?"
• "Show me our OKRs"
• "What ideas are in discovery?"

Real-world use cases

Morning standup prep

"Summarize what changed on our Product Roadmap in the last week"

Stakeholder updates

"List all Q1 objectives and their progress"

Idea triage

"Show me all ideas tagged 'enterprise' that don't have a priority set"

Launch coordination

"What tasks are still incomplete for the January launch?"

Quick lookups

"When is the 'Mobile App v2' bar scheduled to start?"

What ProductPlan data can you access?

List tools take filters, so you can ask for exactly what you need: bars by name, dates, lane, legend or tag, and ideas, opportunities, launches and roadmaps by name or status.

Some things the ProductPlan API itself does not allow, so no tool can do them: creating legends, setting lane colors, writing comments, removing a bar from its container once nested, and creating Azure DevOps or Jira integration links (links made through the API are plain web links).

How it works

┌─────────────────┐      spawns       ┌─────────────────┐      API calls     ┌─────────────────┐│   AI Assistant  │ ───────────────── │   MCP Server    │ ─────────────────▶ │   ProductPlan   ││ (Claude, Cursor)│ ◀───────────────▶ │   (this binary) │ ◀───────────────── │      API        │└─────────────────┘   stdin/stdout    └─────────────────┘     JSON data      └─────────────────┘      your computer                        your computer                         cloud

Why does this need to run on your computer?

MCP (Model Context Protocol) works through a subprocess model. Your AI assistant doesn't connect to a remote server; it spawns the binary as a local process and communicates via stdin/stdout. This architecture means:

1. The binary must exist locally because your AI assistant runs it as a child process
2. Your API token stays on your machine, never passing through third-party servers
3. Real-time, synchronous communication without network latency between AI and the MCP server
4. Works offline for cached data (though ProductPlan API calls still need internet)

When you ask "What's on our Q1 roadmap?", here's what happens:

1. Your AI assistant recognizes it needs ProductPlan data
2. It sends a structured request to the MCP server process
3. The binary translates this into ProductPlan API calls
4. ProductPlan returns JSON data
5. The binary formats and returns results to your AI
6. Your AI presents the answer in natural language

Agent Skills

Pre-built workflow guides that teach AI assistants how to use ProductPlan tools effectively. Each skill targets a specific persona with tailored workflows.

Shared Principles

All skills follow these output conventions:

• No raw JSON - Format responses as readable text and tables
• Human-readable dates - Use "March 2025" or "Q1 2025", not "2025-03-15"
• Summarize large lists - Don't overwhelm with 50 items; offer to expand

Persona-specific variations:

• PM includes bar_id for follow-up actions
• Leadership leads with executive summary, hides implementation details
• Customer-facing omits internal IDs, lane names, and OKRs entirely

To use a skill, copy the SKILL.md file to your Claude Code skills directory:

# Copy a skill (example: PM skill)cp skills/productplan-pm/SKILL.md ~/.claude/skills/productplan-pm.md

Or reference skills directly in your prompts:

"Use the productplan-pm workflow to show me our Q1 roadmap"

Troubleshooting

"Command not found" or "spawn ENOENT"

Your AI assistant can't find the binary. This means:

• Mac/Linux: The file isn't at /usr/local/bin/productplan, or you forgot to run chmod +x
• Windows: The path in your config doesn't match where you saved the .exe

Fix: Verify the binary exists at the path in your config. Run ls -la /usr/local/bin/productplan (Mac/Linux) or check if C:\Tools\productplan.exe exists (Windows).

Windows path issues

Common mistakes on Windows:

Windows uses backslashes (\) for paths, but JSON treats backslash as an escape character. You must double them (\\) in your config file.

"Invalid API token"

Double-check your token at ProductPlan Settings → API. Tokens can expire or be regenerated. Make sure you copied the full token without extra spaces.

"No roadmaps found"

Your API token only accesses data you have permission to see in ProductPlan. Check that your account has access to the roadmaps you're looking for.

AI assistant doesn't see ProductPlan tools

MCP servers load when your AI assistant starts, not when configs change. After editing your config file, fully quit and restart the application. On Mac, use Cmd+Q (not just closing the window).

A bar's color didn't change

Colors are set by legend name (for example "Committed"), not by an ID. Ask your assistant to list the roadmap's legends first. Versions before 6.0.0 sent a legend_id, which ProductPlan treats as "remove the color"; upgrade if colors keep disappearing.

"unknown argument" errors

Since 6.0.0 the server refuses arguments a tool doesn't have, and suggests the closest valid one ("did you mean legend?"). That usually means the assistant guessed a parameter name; it can retry with the suggestion.

"Permission denied" on Mac/Linux

The binary needs execute permission. Run:

chmod +x /usr/local/bin/productplan

Command line (optional)

You can also use this tool directly in Terminal without an AI assistant:

# First, set your tokenexport PRODUCTPLAN_API_TOKEN="your-token"
# Then run commandsproductplan status           # Check connectionproductplan roadmaps         # List all roadmapsproductplan bars 12345       # List bars in roadmap #12345productplan objectives       # List all OKRsproductplan ideas            # List all ideasproductplan opportunities    # List all opportunitiesproductplan launches         # List all launches

Optional setting: PRODUCTPLAN_CACHE_TTL controls how long read results are cached in memory (default 60s; 0 turns the cache off). Any change you make through the server clears the cache immediately.

Background info

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools. Anthropic created it; other AI providers are adopting it. This server implements MCP so your AI assistant can read and write ProductPlan data.

What is ProductPlan?

ProductPlan is roadmap software used by 4,000+ product teams. It handles roadmaps, OKRs, idea discovery, and launch coordination.

For Developers

productplan-mcp-server/├── cmd/productplan/main.go      # Entry point: token check, then MCP server or CLI├── internal/│   ├── api/                     # ProductPlan API client│   │   ├── client.go            # HTTP client: auth, rate limiting, error wrapping│   │   ├── transport.go         # Tuned HTTP transport│   │   ├── cache.go             # In-process TTL read cache (singleflight, write invalidation)│   │   ├── list.go              # Paged collection GETs and Ransack query encoding│   │   ├── ids.go               # Typed resource IDs (BarID, RoadmapID, ...), each validated into a path segment│   │   ├── path.go              # Routes and request paths built only from typed IDs│   │   ├── safeseg.go           # Path-segment validation for user-supplied IDs│   │   ├── endpoints*.go        # Endpoint methods (roadmaps, bars, ideas, launches, OKRs)│   │   ├── bars_read.go         # Roadmap bars with lane enrichment and client-side filters│   │   ├── bar_schema.go        # Roadmap legends/lanes/custom fields for bar writes│   │   └── formatters.go        # Response projection for AI│   ├── mcp/                     # MCP wiring over the official go-sdk│   │   ├── sdk_server.go        # Serves the registry via go-sdk (stdio)│   │   ├── sdk.go               # Converts local Tool -> SDK tool│   │   ├── handler.go           # Registry: dispatch and panic recovery│   │   ├── argkeys.go           # Rejects undeclared argument keys (did-you-mean)│   │   ├── editdistance.go      # Levenshtein distance for suggestions│   │   └── types.go             # Tool-authoring types│   ├── tools/                   # Tool definitions and handlers│   │   ├── registry.go          # Tool registration (name -> handler)│   │   ├── definitions*.go      # Tool schemas and descriptions│   │   ├── helpers.go           # typedHandler, manage-action dispatch│   │   ├── filters.go           # List-tool filters -> Ransack predicates│   │   ├── formatter.go         # List/item/action response summaries│   │   ├── item_type.go         # Item nouns for summaries│   │   ├── bar_planner.go       # Validates bar writes against the roadmap│   │   ├── bar_names.go         # Legend/lane/custom field name resolution│   │   ├── bulk_bars.go         # bulk_update/create/delete_bars│   │   ├── roadmaps.go, bars.go, ideas.go, objectives.go, launches.go, utility.go  # handlers│   │   └── types*.go            # Typed argument structs for handlers│   ├── cli/                     # CLI commands (status, roadmaps, etc.)│   │   └── cli.go│   └── logging/                 # slog JSON handler setup (ts/level/msg)│       └── logger.go├── pkg/productplan/             # Reusable utilities│   ├── retry.go                 # Exponential backoff with jitter│   ├── ratelimit.go             # Adaptive rate limiting│   ├── batch.go                 # Batched operations│   ├── health.go                # Health reporting│   ├── requestid.go             # Request tracing│   ├── validation.go            # ID validation (Field.RequireID)│   └── errors.go                # APIError and error suggestions└── evals/                       # LLM evaluation test suite    ├── runner.go, types.go    ├── tool_selection.json    ├── confusion_pairs.json    └── argument_correctness.json

git clone https://github.com/olgasafonova/productplan-mcp-server.gitcd productplan-mcp-servergo build -o productplan ./cmd/productplan

# macOS Apple SiliconGOOS=darwin GOARCH=arm64 go build -o dist/productplan-darwin-arm64 ./cmd/productplan
# macOS IntelGOOS=darwin GOARCH=amd64 go build -o dist/productplan-darwin-amd64 ./cmd/productplan
# LinuxGOOS=linux GOARCH=amd64 go build -o dist/productplan-linux-amd64 ./cmd/productplan
# WindowsGOOS=windows GOARCH=amd64 go build -o dist/productplan-windows-amd64.exe ./cmd/productplan

go test ./...

go test ./... -cover

go test ./internal/... -bench=. -benchmem

./scripts/run-evals.sh

{"tool": "list_roadmaps", "arguments": {}}{"tool": "manage_bar", "arguments": {"action": "create", "roadmap_id": "123", "lane": "Backend", "name": "New feature", "legend": "Committed"}}{"tool": "bulk_update_bars", "arguments": {"set": {"legend": "Committed"}, "items": [{"bar_id": "901"}, {"bar_id": "902"}], "dry_run": true}}{"tool": "manage_idea", "arguments": {"action": "create", "name": "Mobile app improvements"}}

┌──────────────────────────────────────────────────────────────┐│                        cmd/productplan                        ││                     (entry point, DI)                         │└──────────────────────────────────────────────────────────────┘                              │        ┌─────────────────────┼─────────────────────┐        ▼                     ▼                     ▼┌───────────────┐    ┌───────────────┐    ┌───────────────┐│  internal/cli │    │  internal/mcp │    │internal/tools ││  (CLI cmds)   │    │  (MCP / SDK)  │    │  (handlers)   │└───────────────┘    └───────────────┘    └───────────────┘                              │                     │                              └──────────┬──────────┘                                         ▼                              ┌───────────────────┐                              │   internal/api    │                              │  (HTTP client)    │                              └───────────────────┘                                         │                                         ▼                              ┌───────────────────┐                              │  ProductPlan API  │                              └───────────────────┘

// Tool handler interface (internal/mcp)type Handler interface {    Handle(ctx context.Context, args map[string]any) (json.RawMessage, error)}
// Logging (internal/logging): a *slog.Logger with a JSON handler on stderrlogger := logging.New(slog.LevelInfo)

{"ts":"2026-09-24T10:30:00.123456789Z","level":"debug","msg":"API response","endpoint":"/roadmaps/5","status_code":200,"dur_ms":245}

Changelog

See CHANGELOG.md for release history and detailed changes.

Like This Project?

If this server saved you time, consider giving it a ⭐ on GitHub. It helps others discover the project.

More MCP Servers

Check out my other MCP servers:

License

MIT License - see LICENSE