priorrun-mcp

MCP server for Prior.Run — run focus-group rooms and deep tests on ad creatives and live pages 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

Room-first, mirroring the web app: every deep run starts from a focus-group room. Flow: list_custom_audiences → persona_audience_panel (seats the members) → persona_audience_ask (fast) → deep-run via a create_* tool with custom_audience_id + panel_member_indices (the seated members, both required).

Image arguments accept local file paths, https:// URLs, or base64.

create_url_audit queues a walk and, by default (wait=True), polls until it lands and returns the walk itself. One agent walks the whole page in a real browser, which takes 45–55 minutes — so pass wait=False and poll get_url_audit(walk_id) yourself if your host has a tool timeout under an hour, or if you have anything else to be getting on with.

Example prompts

The agent picks the right tool from your wording. Say "ask my room" / "what do they think" for the room tools, or "live page" / "walk this URL" for the URL tools.

URL walk — the panel walks the page in a real browser, on the screen you name:

Walk brand.com/landing on a phone with my Gen Z skincare room.

→ agent calls create_url_audit with device="mobile" and the seated members, waits out the walk (45–55 min) and returns it: the walker's own account of the page, every finding pinned to the screen it was found on, and one fix per finding in the order to do them. Leave the device out for a 1280px laptop.

Environment variables

Links

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