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

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: bash 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.

Profile	Tools
full (default)	everything
media	wallet models image video realface music speech
trading	wallet price dex markets surf defi rpc
research	wallet models chat search exa surf
chat	wallet models chat

# 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:

Method	Steps
Coinbase	Send → USDC → Base network → paste address
Bridge from Ethereum	bridge.base.org

$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

Tool	Data source	Cost
blockrun_chat	66+ LLMs (GPT, Claude, Gemini, DeepSeek, Kimi K2.6, GLM, NVIDIA free tier, ...) with mode tier routing	per token
blockrun_image	Generation: openai/gpt-image-2 ($0.06–0.12) — flagship, reasoning + text; openai/gpt-image-1 ($0.02–0.04); google/nano-banana ($0.05) / nano-banana-pro ($0.10–0.15, 4K); xai/grok-imagine-image ($0.02) / -pro ($0.07); zai/cogview-4 ($0.015). Edit: openai/gpt-image-, google/nano-banana (img2img, inpaint, fusion).	$0.015–0.15
blockrun_video	Sora 2 + xAI Grok Imagine Video + ByteDance Seedance 1.5/2.0/2.0-fast (720p + audio defaults); RealFace asset → real-person video	$0.05–0.30/sec
blockrun_realface	Enroll a real person (phone liveness) or an AI character (Virtual Portrait, no liveness) as a ta_xxxx asset for Seedance 2.0 video	free; $0.01 to enroll
blockrun_music	MiniMax music generation	per track
blockrun_speech	ElevenLabs text-to-speech (Flash/Turbo/Multilingual/v3, 8 voice aliases) + cinematic sound effects; free voice listing	$0.05–0.10/1k chars; $0.0525/effect
blockrun_price	Pyth-backed realtime + OHLC — crypto / FX / commodity (free), 12 stock markets (paid)	free or $0.001/call
blockrun_markets	Polymarket (markets, candles, trades, orderbooks, leaderboards, smart-wallet PnL/clusters, UMA oracle), Kalshi, Limitless, Opinion, Predict.Fun, dFlow, Binance Futures, cross-platform match + search	$0.001–0.005/query
blockrun_surf	Surf (asksurf.ai) — 84 endpoints: CEX market data, on-chain SQL (13 chains, 80+ ClickHouse tables), 100M+ labeled wallets, Polymarket + Kalshi side-by-side, social mindshare, news, search, Surf-1.5 chat with citations	$0.001–0.02/call
blockrun_exa	Neural web search (Exa) — research, competitors, papers, URL content	$0.01/query
blockrun_search	Grok Live Search — web + X/Twitter + news with citations	$0.025 × max_results (default 10)
blockrun_dex	Live DEX prices via DexScreener	free
blockrun_rpc	Raw JSON-RPC on 40+ chains (Ethereum, Base, Solana, Bitcoin, Sui, NEAR, ...) via Tatum gateway — eth_call, balances, blocks, logs	$0.002/call
blockrun_defi	DefiLlama — protocol TVL, chain TVL, yield pools (APY), token prices	$0.001–0.005/call
blockrun_modal	Isolated code execution in a BlockRun-hosted Modal sandbox — disposable container, optional GPU (T4 → H100)	$0.01 create; $0.001/op
blockrun_phone	Outbound AI voice calls (Bland) + wallet-owned US/CA numbers (Twilio), carrier + fraud lookups	$0.54/call; $5/number
blockrun_models	Live catalogue of every LLM/image/video/music model + pricing	free
blockrun_wallet	Balance, spending, agent budgets, setup QR	free

---

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/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..." }

---

Why not just use the APIs directly?

	Direct APIs	BlockRun
Exa	Sign up, $20/mo minimum	$0.01/call, no subscription
Polymarket	Undocumented, rate-limited	$0.001/call, clean JSON
Surf (asksurf.ai)	Account + monthly plan	$0.001/call, no Surf account, 84 endpoints
Multiple sources	3 accounts, 3 API keys, 3 billing pages	1 wallet

One wallet. All sources. No dashboards.

---

When NOT to use BlockRun MCP

BlockRun shines when you want unified billing + many sources + LLM-readable errors. It is not the right fit for:

• High-volume single-API workloads (≥10k calls/day to one source). Direct