priorrun-mcp 0.4.1

Run Prior.Run audience simulations from Claude Desktop, Claude Code, Cursor, or any MCP-compatible agent.

priorrun-mcp

MCP server for Prior.Run — run synthetic-audience simulations on design variants and ad creatives from Claude Desktop, Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Cline, Zed, or any MCP-compatible agent.

Install

Requires Python 3.11+. Install uv if you don't have it.

uvx priorrun-mcp

That's it — uvx fetches and runs the server on demand.

Configure

Grab an API key from prior.run/settings, then register the server with your agent host.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "prior-run": {
      "command": "uvx",
      "args": ["priorrun-mcp"],
      "env": {
        "PRIORRUN_API_KEY": "pr_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Code

~/.claude/mcp.json (global) or .mcp.json in a project root:

{
  "mcpServers": {
    "prior-run": {
      "command": "uvx",
      "args": ["priorrun-mcp"],
      "env": { "PRIORRUN_API_KEY": "pr_live_..." }
    }
  }
}

Codex (OpenAI)

~/.codex/config.toml — TOML, not JSON:

[mcp_servers.prior-run]
command = "uvx"
args = ["priorrun-mcp"]

[mcp_servers.prior-run.env]
PRIORRUN_API_KEY = "pr_live_..."

Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "prior-run": {
      "command": "uvx",
      "args": ["priorrun-mcp"],
      "env": { "PRIORRUN_API_KEY": "pr_live_..." }
    }
  }
}

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "prior-run": {
      "command": "uvx",
      "args": ["priorrun-mcp"],
      "env": { "PRIORRUN_API_KEY": "pr_live_..." }
    }
  }
}

Windsurf / Cline / Zed / other MCP hosts

All modern MCP hosts share the same mcpServers JSON shape used by Claude Code. Drop the same block into the host's MCP config file — check the host's docs for the exact path.

Tools

Tool	What it does
create_design_review	single design review
create_design_compare	two design variants head-to-head
create_design_multi	3–5 design variants
create_design_flow	two funnel flows (each 2–5 screens)
create_ads_single	single ad creative evaluation
create_ads_compare	two ad creatives head-to-head
create_ads_multi	3–5 ad creatives
create_creative_from_fieldnotes	3 ad creative variants (quote / editorial / bold graphic) generated from a focus-group's field notes — no memo required
get_memo	fetch status + full memo JSON by id
wait_for_memo	block until synthesis completes

Image arguments accept local file paths, https:// URLs, or base64. Create tools default to wait=True — the agent gets the completed memo in one tool call.

Example prompts

The agent picks the right tool from your wording. Say "ad creative" / "creative compare" / name a platform (Meta/TikTok/Google) for the ads tools, or "landing page" / "design compare" / "variant" for the design tools.

Design compare — evaluates the page itself (layout, hierarchy, CTA clarity, conversion readiness):

Run a Prior.Run design compare on ~/desktop/landing-a.png vs
~/desktop/landing-b.png targeting the gen_z audience template. Hypothesis:
the warmer palette will lift click-through.

→ agent calls create_design_compare, full page-level synthesis, burns 1 analysis credit.

Ads compare — evaluates the creative as it would appear in-feed (scroll-stop, hook clarity, brand recall), platform-aware:

Run a Prior.Run ads compare on ~/desktop/creative-a.jpg vs
~/desktop/creative-b.jpg. Campaign context: Gen Z skincare awareness on TikTok.

→ agent calls create_ads_compare with run_platform="tiktok", ads-specific synthesis (scroll-stop, hook, brand recall, no landing-page critique).

Both return a completed memo (~90s) with verdict, audience quotes, and a memo URL.

Environment variables

Variable	Required	Default	Notes
PRIORRUN_API_KEY	yes	—	pr_live_... format. Generate at prior.run/settings.
PRIORRUN_API_BASE	no	https://api.prior.run	Override for staging or local dev.

Links

• Product: prior.run
• API docs: prior.run/docs/api
• MCP docs: prior.run/docs/mcp