BlockRun MCP

Real-time data — and real trades — for Claude. Markets, research, web search, crypto; read the odds and place the bet on Polymarket. 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.

🏆 First of its kind — the signal → trade loop in Claude Code. Read live Polymarket odds and place USDC-settled bets, from one self-custody wallet, pay-per-call. Jump to Polymarket trading →

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?"
• "Polymarket has the Fed holding at 73% — put $2 on it." ← and now it can place the trade, not just read the odds.

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)

User: Polymarket has Hawley at ~13% to announce a 2026 presidential run — put $1 on Yes.

Claude: Done — bought 7.63 shares of Yes at $0.131 ($1.00, market FOK). Real on-chain order, settled in pUSD from your gasless Polymarket deposit wallet; I'm tracking the position now.

(signal via blockrun_markets, trade via blockrun_polymarket — one self-custody wallet, gasless · on-chain tx 0x7ca8…)

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

Cornell Blockchain Conference 2026 — packed booth recap	Cornell Blockchain Conference 2026 — quiet variant	100 Trillion Tokens — milestone synthwave poster

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

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_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_image pays on either chain.)
• 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.
• CRITICAL: blockrun_polymarket moves REAL user funds (pUSD on Polygon), separate from the x402 API budget. Never call buy/sell/redeem with confirm:true unless the user explicitly approved that exact trade; without confirm you get a safe dry-run preview. Discover markets/token IDs with blockrun_markets first.
• 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/batch, wallet/detail, wallet/net-worth

4. Cited research with sources

   "Find the 5 most-cited papers on speculative decoding from the last 90 days. Summarize the dominant approach." → blockrun_exa action:search then contents

5. Image generation with on-image text

   "Generate a poster announcing GPT-5.5 on BlockRun, retro-futuristic, with the headline 'NOW LIVE'." → blockrun_image + the image-prompting skill 5-section framework

6. Give your agent a voice

   "Use blockrun to speak this with the sarah voice." → blockrun_speech action:speak (default), input + voice → hosted MP3 URL. Sound effects via action:sound_effect

7. Voice phone-out

   "Call +1-415-555-... and confirm the appointment on Friday at 3pm." → blockrun_phone path:voice/call, body: { to, task, from } (provision from first via phone/numbers/buy), then poll voice/call/{call_id}

8. Multi-agent research with budget cap

   "Spawn 3 research agents on competing L1 narratives. Cap each at $0.50." → blockrun_wallet delegate × 3 → children call blockrun_chat + blockrun_exa with their agent_id

9. Cross-chain SQL forensics

   "Top 10 tokens by DEX volume on Base in the last 24h." → blockrun_surf path:onchain/sql, body: { sql: "SELECT..." }

10. Prediction-market signal → trade (the full loop, self-custody)

    "What are Polymarket's odds the Fed holds in May? If it's under 30%, put $2 on Yes." → blockrun_markets reads the signal → blockrun_polymarket action:"buy" places the trade. One wallet, gasless, confirm-gated — the first signal-to-trade loop in Claude Code.

Why not just use the APIs directly?

One wallet. All sources. No dashboards.

Multi-agent budget delegation

Delegate a spending budget to a child agent with agent_id. The child is auto-blocked when the budget runs out — useful for autonomous agents that shouldn't run up unbounded costs.

Troubleshooting

• Insufficient balance / HTTP 402 after retry → Run blockrun_wallet action:"setup". Send USDC on Base (or Solana — see Environment Variables).
• Smart routing (ClawRouter) is not available on Solana → Pass model: or mode: explicitly to blockrun_chat, or switch back to Base with echo base > ~/.blockrun/.chain.
• blockrun doesn't connect / "MCP server failed" / spawn npx ENOENT → Almost always a PATH issue: Claude Code can't find node/npx on the PATH its MCP launcher uses. Common with Homebrew (/opt/homebrew/bin) or nvm, where node isn't on that PATH — and it affects the CLI as well as the desktop app (the launcher doesn't always inherit your interactive shell PATH). Fix by passing your shell PATH at install:

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

  Then restart Claude Code (or /mcp to reconnect — MCP tools load at session start). Or pin absolute paths: claude mcp add blockrun -s user -- /opt/homebrew/bin/npx -y @blockrun/mcp@latest (use which npx for your path).
• claude mcp list doesn't show blockrun → Check node -v (must be ≥20.19). Clear the npx cache: rm -rf ~/.npm/_npx. Re-run the install command from above (see the PATH fix above if node/npx aren't found).
• fetch failed / timeout when checking wallet balance → Base RPC transient outage. The tool already falls through 3 public RPCs; retry after 30s. Persistent failures usually = local proxy / firewall blocking outbound RPC.
• ENOENT: ~/.blockrun/.session → Expected on first run. The server auto-creates the wallet; check stderr for the WALLET_CREATED line confirming the address.
• Video generation timed out (5-min cap) → Upstream Seedance / xAI queue congestion. No charge (payment-on-completion). Retry, or pick a faster model (bytedance/seedance-1.5-pro).
• Music generation timed out (200s cap) → Same pattern. No charge. Retry; if it persists, the upstream model is rate-limited — try off-peak.

Polymarket trading

blockrun_polymarket lets an agent place real bets on Polymarket (CLOB V2, Polygon). It is non-custodial: every order and approval is EIP-712-signed locally by your BlockRun wallet key (~/.blockrun/.session) — the same self-custody key that pays x402 API fees on Base also authorizes bets on Polygon. Neither BlockRun nor Polymarket's relayer can move funds; they only forward payloads you signed.

Architecture — the official "deposit wallet" path (signature type POLY_1271): a small smart-contract vault on Polygon, CREATE2-derived from your key (only your key can authorize it), holds the betting funds in pUSD (Polymarket's 1:1 collateral wrapper; backing is migrating to native Circle USDC). Deployment, exchange approvals, and redemptions all run gasless through Polymarket's relayer — you never need POL.

Full step-by-step setup + test guide: docs/polymarket-trading-setup.md.

Getting started:

1. No Polymarket account, API keys, or gas token needed — the MCP bootstraps the builder credentials for the gasless relayer from your own wallet on first setup, and the geoblock egress is handled by default (see Regions below).
2. blockrun_polymarket action:"setup" — derives + deploys your deposit wallet and prints its address.
3. Fund it gaslessly from your Base USDC in one call: action:"fund" amount_usd:5 confirm:true. BlockRun pays the Base gas and charges $0.01; non-custodial — your USDC goes straight to the Polymarket bridge and wraps to pUSD in your vault. The credit is async (minutes) — re-run setup to watch the balance.
4. action:"setup" confirm:true — signs the one-time gasless approval batch (Polymarket's canonical set: pUSD spend for both exchanges, the NegRisk Adapter, and the Conditional Tokens contract, plus the CTF operator approvals — the NegRisk Adapter grant is what lets multi-outcome "winner" markets settle). Setup reads approvals on-chain every run, so re-running it after an upgrade grants any newly-required approval.
5. Find a market with blockrun_markets, then action:"buy" — without confirm:true you get a dry-run preview; with it, the order is signed and placed.
6. Cash out any time: action:"sell" (before resolution) or action:"redeem" (after you win) turns the position into pUSD, then action:"withdraw" bridges it back to native USDC on Base — the same wallet that pays your AI fees.

Safety rails (server-side; an agent cannot bypass them): confirm:true required for every order/approval/redeem, POLYMARKET_MAX_BET_USD per-order cap (default $25), optional POLYMARKET_MAX_SESSION_USD session cap, and bets never draw from the x402 API budget.

Regions: Polymarket geoblocks order placement by IP (US/UK/EU + many regions). Handled by default — the MCP routes CLOB traffic through BlockRun's hosted Tokyo egress, so trading works out of the box; setup reports your status. Override POLYMARKET_CLOB_HOST to go direct or run your own egress.

To route through a permitted egress you operate (e.g. a small always-on VM in an unrestricted region), two options:

• HTTPS_PROXY=http://user:pass@host:port (simplest). Both Polymarket SDK HTTP clients (CLOB and the relayer) honor it natively, while @blockrun/llm's x402/LLM traffic uses fetch and stays direct — so in practice only Polymarket traffic is routed, without touching your API-payment egress. Best when someone runs the demo from a restricted region on their own machine.
• POLYMARKET_CLOB_PROXY=http://user:pass@host:port (surgical). Routes only Polymarket traffic — CLOB order placement, the L1-auth/derive calls, the geoblock check, and the relayer's deploy/approve/redeem POSTs (injected into the relayer's own axios instance). Use this if you want to leave every other env var untouched.

Run your egress proxy authenticated (not an open relay — open proxies get abused within hours). Complying with Polymarket's terms for your jurisdiction is your responsibility.

EOA mode: POLYMARKET_SIG_TYPE=0 uses the key's own address (no deposit wallet, no relayer creds) for reads and credential derivation. Note: CLOB V2 rejects a plain EOA maker for order placement (maker address not allowed, please use the deposit wallet flow), so use the default deposit-wallet mode to actually place orders.

⚠️ Back up ~/.blockrun/.session. It is the only key to both the payment wallet and the Polymarket deposit wallet.

Environment Variables

Chain selection priority (see src/utils/wallet.ts):

1. ~/.blockrun/.chain or ~/.blockrun/payment-chain set to base or solana → explicit preference wins
2. SOLANA_WALLET_KEY env var present → Solana
3. ~/.blockrun/.solana-session exists → Solana
4. Otherwise → Base (~/.blockrun/.session auto-created)

Switching chains:

The recommended way is the tool itself — it provisions both wallets, applies instantly (no restart), and shows the funding QR:

blockrun_wallet action:"chain" chain:"solana"   # or chain:"base"
blockrun_wallet action:"setup"                  # funding instructions for the active chain

Advanced (force a chain before startup, e.g. in CI): echo solana > ~/.blockrun/.chain then set SOLANA_WALLET_KEY or create ~/.blockrun/.solana-session; echo base > ~/.blockrun/.chain reuses the existing .session (same Base wallet). These edit the same preference file that action:"chain" writes — prefer the tool unless you need pre-startup control.

Some media and paid market-data tools still settle on Base only: blockrun_music, blockrun_speech, blockrun_video, paid blockrun_realface (enroll/portrait), and paid stock blockrun_price calls — plus blockrun_chat routing:"smart" and native Anthropic (claude-*) passthrough. In Solana mode these return a "switch to Base" message instead of charging. blockrun_image (generate + edit) settles on whichever chain is active.

The server also runs a non-blocking npm registry check at startup and prints an Update available notice to stderr when a newer @blockrun/mcp version exists. Upgrade by re-running the install command — no manual npm update needed.

How it works

Pay-per-call via x402 micropayments in USDC. Your wallet lives at ~/.blockrun/.session (Base) or ~/.blockrun/.solana-session (Solana). The private key never leaves your machine.

Contributing

PRs welcome. See CONTRIBUTING.md for setup, the tool-vs-skill design rule, and how to add a new partner API.

Issues: github.com/blockrunai/blockrun-mcp/issues

blockrun.ai · npm · @BlockRunAI