ProductBrain

io.github.moxzasv0.1.0Updated Oct 9, 2026

Drive your ProductBrain product plan (goals, needs, bets, jobs) from any MCP client.

VerifiedSTDIODesktop onlyDeveloper ToolsProductivity & Workflow

Overview

AI-generated overview

Lets an assistant search, read, and modify a ProductBrain product plan — goals, needs, bets, jobs — and drive its live canvas.

What it does
A thin transport over ProductBrain's versioned v1 REST API, exposing one tool per agent-facing endpoint. Tools cover semantic search, bulk node reads, tree context, node and phase mutations, iteration listing, the Story-Mapping workflow, OKF export, and plan changelog. It also drives or reads the live canvas, and manages projects, webhooks, share links, members, agent seats, and tier status.
When to use it
Use it when a team keeps its product plan in ProductBrain and wants an assistant to look things up, propose or apply plan changes, run the story-mapping methodology, or manage projects, webhooks, and share links from a chat client.
Requirements
Runs locally over stdio via npx from the npm package @productbrain-com/mcp, so Node.js is needed. Requires a ProductBrain API key in PRODUCTBRAIN_API_KEY (a pb_ key from the app's API Keys settings; the free tier includes API access). PRODUCTBRAIN_PROJECT_ID is optional, and PRODUCTBRAIN_API_URL defaults to the hosted API. Desktop clients only.
Before you install
The API key is a secret and grants access to your plan. Mutate can create, update, and delete nodes and phases, and project tools can archive projects; webhook and share-link tools can register endpoints or mint public read-only links, and create_webhook and add_agent_seat return signing secrets or keys only once. Some tools are Team-tier only. Plan data is sent to ProductBrain's hosted API.

Installation

In SourceWeft

  1. Open ProductBrain in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

ProductBrain MCP server

Drive your ProductBrain plan from an MCP client — Claude Desktop, Cursor, Claude Code — with tools for search, read, mutate, the methodology workflow, and the live view.

Design — a thin shim, on purpose

This server is a thin transport over ProductBrain's versioned v1 REST API. Each tool is one call to an existing /api/v1 endpoint. The REST contract stays canonical:

  • It's stable when the MCP spec churns — the contract you depend on is the frozen v1 API, not the protocol.
  • You can drop to raw HTTP or bring your own LLM at any time; MCP is one front-door, not the only one.
  • Responses carry the same in-band _meta coaching the API returns, so your agent self-corrects.

Install

jsonc
// Claude Desktop — claude_desktop_config.json{  "mcpServers": {    "productbrain": {      "command": "npx",      "args": ["-y", "@productbrain-com/mcp"],      "env": {        "PRODUCTBRAIN_API_KEY": "pb_your_key",        "PRODUCTBRAIN_PROJECT_ID": "your-project-id"      }    }  }}
bash
# Claude Codeclaude mcp add productbrain \  -e PRODUCTBRAIN_API_KEY=pb_your_key \  -e PRODUCTBRAIN_PROJECT_ID=your-project-id \  -- npx -y @productbrain-com/mcp

Cursor and other clients: add an mcpServers entry with the same command/args/env.

Config (env)

VarRequiredDefault
PRODUCTBRAIN_API_KEYyes— (your pb_ key from the app's API Key modal)
PRODUCTBRAIN_PROJECT_IDno— (tools also accept a projectId argument)
PRODUCTBRAIN_API_URLnohttps://productbrain.com/api/v1

Tools

Every agent-facing /api/v1 endpoint has a tool. One tool, one endpoint, same _meta coaching passed back verbatim.

The plan

ToolMaps toUse
searchGET /searchSemantic search — use first for any lookup
list_nodesGET /nodesBulk read, optional type/iteration filter
get_treeGET /treeA node in context (ancestors/siblings/children/subtree)
mutatePOST /mutateCreate/update/delete nodes + phases; pass idempotencyKey to make retries safe
list_iterationsGET /iterationsPhases; current:true for the active one
run_workflowPOST /workflowStory-Mapping methodology (add / task-curate / phase-assign)
export_okfGET /export-okfThe plan as a portable OKF file bundle
get_changelogGET /changelogPlan history: every add/update/delete/restore, attributed to the app or a named agent

The view

ToolMaps toUse
set_view / read_viewPOST /view-command, GET /view-stateDrive / read the live canvas

Projects

ToolMaps toUse
list_projectsGET /projectsProjects you own or are a member of; includeArchived for the rest
create_projectPOST /mutate {addProject}Bootstrap a brain — seeds the system "Later" phase. Pass an explicit id: addProject runs before mutate reads Idempotency-Key, so it is not retry-safe
rename_projectPOST /mutate {renameProject}Change the display name; the id is immutable
archive_projectPATCH /projectsHide/unhide without deleting (reversible)

Webhooks

ToolMaps toUse
list_webhooksGET /webhooksRegistered hooks with lastStatus — spot a failing receiver
create_webhookPOST /webhooksRegister; returns the signing secret once
update_webhookPATCH /webhooksChange url/events in place, or rotateSecret:true. Prefer over delete+recreate
delete_webhookDELETE /webhooksRemove a registration

Share links

ToolMaps toUse
create_share_linkPOST /shareMint a public read-only link; expiresInDays for a TTL
list_share_linksGET /shareAudit every token minted, with an active flag
revoke_share_linkDELETE /shareKill a leaked or stale link

Members and budget

ToolMaps toUse
list_membersGET /membersHumans and agent seats on a project
add_agent_seatPOST /membersMint an agent seat; the pb_ key is returned once (Team tier)
invite_contributorPOST /membersPasswordless guest invite, scoped to the projects you name (Team tier)
revoke_memberDELETE /membersRemove a seat; an agent's key dies with its last membership
tier_statusGET /tier-statusYour tier, API access, credit balance and limits — check before a large run
submit_feedbackPOST /feedbackTell the PB team what to improve: feature requests, friction, bugs, notes

Full API reference: https://productbrain.com/docs/llm-guide.md.

Source, licence, registry

  • Source: https://github.com/moxzas/productbrain-mcp (MIT). Issues and pull requests welcome there.
  • npm: @productbrain-com/mcp. Every release is published from the repository's tag of the same version.
  • MCP registry name: io.github.moxzas/productbrain (server.json in this repo is the registry manifest).
  • The server sends User-Agent: productbrain-mcp/<version> so you can tell MCP traffic from raw REST calls in your own logs.

Proving it works

Two headless scripts in the repository (src/spike-proof.ts, src/parity-proof.ts; not shipped in the npm package), both run against a real deployment. Use a throwaway project on your own account:

bash
PRODUCTBRAIN_API_KEY=pb_your_key \PRODUCTBRAIN_PROJECT_ID=your-sandbox-project \npm run spike     # transport + auth + one read + one write
PRODUCTBRAIN_API_KEY=pb_your_key \npm run parity    # every non-plan tool once, on a throwaway project

parity creates its own throwaway project and cleans up after itself (archiving it at the end — there is no project-delete endpoint).

The Team-tier tools (add_agent_seat, invite_contributor) return 403 team_tier_required on a Builder key, and that counts as a pass — with one caveat worth knowing. It proves the shim reached the right route and passed the error and its _meta tip straight through; it does not validate the request body, because the tier gate runs before the body is read. Run parity with a Team-tier key to check those two properly.

Source: README.md at commit 501f630

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.1.0LatestOct 9, 2026