Blockrun

BlockRun MCP

Real-time data for Claude — markets, research, X/Twitter, crypto. No API keys. Pay per call.

claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest

Wallet auto-created. Fund with $5 USDC. Ask Claude anything.

Documentation

Full docs: https://blockrun.ai/docs

• MCP tools & setup: https://blockrun.ai/docs/mcp/blockrun-mcp
• All BlockRun SDKs & APIs: https://blockrun.ai/docs

What changes

Before BlockRun, Claude can't answer:

• "What's the current Polymarket probability that Bitcoin hits $100k this year?"
• "Find me the top 5 papers on RAG published in the last 30 days"
• "What are people saying about @sama on X right now?"
• "What's the 24h volume on the PEPE/ETH pair on Uniswap?"

After BlockRun, it can. Each query costs fractions of a cent, billed from a local USDC wallet. No subscriptions. No API dashboards. No key rotation.

Demo

User: What's Polymarket saying about the Fed rate decision next month?

Claude: According to Polymarket, the market currently puts a 73% probability on the Fed holding rates steady at the May meeting, with 24% on a 25bp cut and 3% on a hike. Volume over the last 24h: $2.1M. The "Hold" contract last traded at $0.73.

(via blockrun_markets · cost: $0.001)

User: Find recent papers on speculative decoding and summarize the key approaches

Claude: I found 8 papers from the last 60 days via neural search. The dominant approaches are: (1) draft model selection — smaller models predicting N tokens ahead for the larger model to verify in parallel...

(via blockrun_exa · cost: $0.01)

Showcase

Posters generated through blockrun_image with openai/gpt-image-2. Each is a single API call routed through BlockRun, paid in USDC on Base.

Latest — GPT-5.5 now live on BlockRun

Gallery

Prompts and a worked example for these are in skills/image-prompting/SKILL.md.

Prerequisites

• Node.js ≥ 20.19 (node -v)
• ~$5 USDC on Base or Solana (the server auto-creates a wallet on first run; see Fund your wallet)
• An MCP client: Claude Code, Claude Desktop, Cursor, Windsurf, or ChatGPT Desktop

Install

Claude Code (recommended)

claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest

The -s user flag installs globally (available in every project). The -- separator ensures -y is passed to npx, not parsed by claude mcp add.

💡 Homebrew / nvm users: if the server doesn't connect after install, Claude Code likely can't find node/npx on its launcher PATH. Install with your shell PATH passed through — works on CLI and desktop:

claude mcp add blockrun -s user -e PATH="$PATH" -- npx -y @blockrun/mcp@latest

Copy to clipboard

See Troubleshooting if it persists.

Tool profiles — expose a trimmed tool set so the client loads fewer schemas into context. Pass --profile <name> (or set BLOCKRUN_MCP_PROFILE); omit it for the full set.

# e.g. a media-only install
claude mcp add blockrun-media -s user -- npx -y @blockrun/mcp@latest --profile media
# or a trading-only install
claude mcp add blockrun-trading -s user -- npx -y @blockrun/mcp@latest --profile trading

Equivalent via env: BLOCKRUN_MCP_PROFILE=trading. An unknown profile name falls back to full. modal and phone are available in the full profile only.

Claude Desktop — add to claude_desktop_config.json:

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

Cursor — add to ~/.cursor/mcp.json (macOS / Linux) or %APPDATA%\Cursor\mcp.json (Windows):

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

Windsurf — same JSON, in:

• macOS: ~/.codeium/windsurf/mcp_config.json
• Linux: ~/.config/.codeium/windsurf/mcp_config.json
• Windows: %APPDATA%\Codeium\windsurf\mcp_config.json

Fund your wallet

Run blockrun_wallet to see your address. The server pays on Base by default. Send USDC on Base:

$5 covers ~5,000 market queries, ~500 Exa searches, ~250 image generations, or ~10 Seedance 1.5-pro clips (5s @ 720p+audio, ~$0.46 each).

Pay on Solana

Prefer to pay in USDC on Solana? It's two tool calls — no env vars, no file editing, no restart:

blockrun_wallet action:"chain" chain:"solana"   # provisions + activates the Solana wallet
blockrun_wallet action:"setup"                  # shows the Solana address + funding QR

Then send USDC (SPL) on the Solana network — from Coinbase (pick "Solana"), Phantom, Solflare, or Backpack. Switch back anytime with blockrun_wallet action:"chain" chain:"base". The server keeps both wallets; switching just changes which one pays.

Base-only — these fall back to Base regardless of active chain:

• Tools: blockrun_image, blockrun_music, blockrun_speech, blockrun_video, paid blockrun_realface (enroll/portrait), paid stock blockrun_price. In Solana mode they return a "switch to Base" message instead of charging.
• blockrun_chat routing:"smart" (ClawRouter) and native Anthropic (claude-*) passthrough — on Solana, pass model: or mode: explicitly.

Advanced: chain selection can also be forced before startup via files/env (~/.blockrun/.chain, SOLANA_WALLET_KEY) — see Environment Variables. The action:"chain" command above is the recommended path.

Tools

Tips for effective LLMs

For LLMs and agents invoking BlockRun MCP tools:

• CRITICAL: When any blockrun_* tool returns a payment / balance / 402 error, call blockrun_wallet first to check status, then action:"setup" to get funding instructions. Don't retry the failing tool blindly — the wallet is empty.
• CRITICAL: blockrun_surf's 84-endpoint catalog lives in skills/surf/SKILL.md; blockrun_markets' full endpoint list is in its own tool description (with worked examples in skills/prediction-markets/SKILL.md). Browse those before guessing endpoint paths.
• CRITICAL: blockrun_chat routing:"smart" (ClawRouter) only works on Base wallets. On Solana, pass mode: or model: to pick a model directly.
• CRITICAL: blockrun_music and blockrun_video are payment-on-completion async. Failures or client-side timeouts do NOT charge. Don't retry-loop them — they may take 60–180s.
• CRITICAL: Before spawning child agents, allocate per-agent budget: blockrun_wallet action:"delegate" agent_id:"X" agent_limit:1.00. Pass agent_id:"X" to every downstream blockrun_* call — the child is auto-blocked when the budget hits zero.
• Free tier first for drafts: blockrun_chat mode:"free" (NVIDIA), blockrun_dex, blockrun_price (crypto / FX / commodity), and blockrun_models are all $0. Use them to scaffold before paying for premium models.

Key Use Cases

What kinds of questions can Claude (or any LLM agent) answer once BlockRun MCP is installed:

1. Price reads / market data

   "What's BTC trading at? Compare with last week's average." → blockrun_price (free) or blockrun_surf path:market/price

2. Prediction-market consensus

   "What's Polymarket's odds for the next Fed rate decision?" → blockrun_markets path:polymarket/events + filter

3. On-chain forensics

   "This wallet (0xabc...) — what's it labeled as? What does it hold? When did it whale up?" → blockrun_surf paths:`wallet/labels/batc

…