@promptbranch/mcp

PromptBranch MCP server

@promptbranch/mcp is a local-first Model Context Protocol server for AI coding agents. It gives an MCP-capable assistant a searchable prompt library with version history, run reports, notes, and human-reviewed improvement proposals. It uses the same local SQLite library as the PromptBranch desktop app.

Requires Node.js 22 or later. No account or hosted database is required for local library operations.

Source: GitHub · MCP integration guide · agent workflow · report an issue

Install

Add the stdio server to any MCP client that supports a command and arguments:

{
  "mcpServers": {
    "promptbranch": {
      "command": "npx",
      "args": ["-y", "@promptbranch/mcp@latest"]
    }
  }
}

This works with MCP-capable tools such as Claude Desktop, Cursor, Windsurf, Cline, and other agent harnesses. The package can also be installed globally:

npm install --global @promptbranch/mcp@latest

Tools

Tool	Purpose
get_prompt	Fetch and render current prompt content or a specific version/branch
search_prompts	Search the library with optional tag, collection, and limit filters
list_prompts	Browse prompt metadata
report_run	Record a 1–5 outcome rating, summary, and metrics
add_note	Attach a note to a prompt or version
suggest_variation	Propose an improved version that stays pending until human approval

The intended agent loop is fetch → run → report → suggest. Agents can read prompts, record evidence about what worked, and propose improvements. Pending suggestions never enter search results or become current until a person reviews them in the desktop app's Suggestions view.

get_prompt returns a stable versionId. Reuse it as versionId with get_prompt or report_run, and as baseVersionId with suggest_variation, whenever the workflow must stay tied to the same version record. A desktop user can amend its content; new versions preserve historical snapshots. Numeric versions are branch-scoped display labels and may contain gaps.

The server deliberately has no publish or import tool. Sharing remains a human action in the desktop app or CLI.

Dynamic prompt variables

get_prompt recognizes placeholders such as {{target}}. If values are missing, it returns status: "needs_input" with requiredVariables and missingVariables. The agent asks the user for those values and calls the tool again with a variables object. Once complete, status is "ready", templateContent contains the stored template, and content contains the rendered prompt.

Variable values may be strings, finite numbers, or booleans. They apply only to that response and are never written back to the library. Variables express prompt instructions; PromptBranch does not interpret values such as an agent count or create subagents itself.

Configuration

Set PROMPTBRANCH_DB=/path/to.db to use a different local library. The desktop app, CLI, and MCP server can share the same SQLite database; legacy PROMPTHUB_DB and PROMPTBUILDER_DB variables remain supported as deprecated fallbacks.

Prompts can be referenced by id or title (exact, case-insensitive, or unique substring). See the MCP integration guide for client configuration and workflow details.

Build from source

From the PromptBranch repository, with pnpm 11.7.0 available:

pnpm install
pnpm --filter @promptbranch/mcp build

The bundled server is dist/index.js.