io.github.BlockRunAI/blockrun-mcp

<img src="https://img.shields.io/badge/🧰_20_Tools-success?style=for-the-badge" alt="20 tools">  <img src="https://img.shields.io/badge/🤖_Agent--Native-black?style=for-the-badge" alt="Agent native">  <img src="https://img.shields.io/badge/🔑_Zero_API_Keys-blue?style=for-the-badge" alt="No API keys">  <img src="https://img.shields.io/badge/📈_Read_+_Trade_Polymarket-e11d48?style=for-the-badge" alt="Read and trade Polymarket">  <img src="https://img.shields.io/badge/💰_x402_USDC-purple?style=for-the-badge" alt="x402 USDC">  <img src="https://img.shields.io/badge/🔓_Open_Source-green?style=for-the-badge" alt="Open source">

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

BlockRun MCP is an open-source Model Context Protocol server that gives Claude — and any MCP-compatible agent — <!-- br:mcp.tools -->20<!-- /br:mcp.tools --> tools for real-time data and real actions: <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> LLMs, image & video generation, prediction-market data, live web/X search, on-chain queries across <!-- br:chains.rpc -->40<!-- /br:chains.rpc --> chains, and the ability to place real, USDC-settled bets on Polymarket. Authentication is a wallet signature (no API keys); you pay per call in USDC via the x402 protocol (no credit cards, no subscriptions). One self-custody wallet on Base or Solana. MIT licensed.

🏆 First of its kind — the signal → trade loop in Claude Code

Read live Polymarket odds and place the bet, from one self-custody wallet, pay-per-call. Jump to Polymarket trading →

Why BlockRun MCP exists

Every other data integration was built for human developers — create an account, copy an API key into .env, add a credit card, repeat for every vendor.

Agents can't do any of that. BlockRun MCP is built for the agent-first world:

• One wallet, every source — <!-- br:mcp.tools -->20<!-- /br:mcp.tools --> tools behind a single self-custody wallet. No per-vendor signups.
• No API keys — your wallet signature is authentication.
• No credit cards — pay per request in USDC via x402, fractions of a cent each.
• Starts free — the free tier (blockrun_chat mode:"free", blockrun_dex, crypto blockrun_price, blockrun_models) costs $0.
• Reads and acts — most tools deliver data; blockrun_polymarket places real, confirm-gated trades.
• Self-custody — your key never leaves your machine (~/.blockrun/.session by default, 0600). BlockRun can't move your funds.

How it compares

✓ One wallet · ✓ Pay-per-call · ✓ Reads and trades · ✓ Multi-chain · ✓ Agent-ready · ✓ Open source

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.

Quick Start

1. Install

Claude Code (recommended)

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

-s user 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, Claude Code likely can't find node/npx on its launcher PATH. Pass your shell PATH 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.

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

2. Choose a tool profile (optional)

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

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

# Codex CLI
codex mcp add blockrun-trading -- npx -y @blockrun/mcp@latest --profile trading

An unknown profile name falls back to full. modal and phone are full-profile only. For a complete live signal → order-preview presentation, use skills/signal-to-trade-demo/SKILL.md with the Stanford runbook.

3. Fund your wallet

Run blockrun_wallet to see your address. The server pays on Base by default — send USDC on Base (Coinbase → USDC → Base network → paste address, or bridge via bridge.base.org).

$5 covers ~525 market queries · ~500 Exa searches · ~250 image generations · ~10 Seedance 1.5-pro clips.

Prefer Solana? See Fund your wallet — two tool calls, no restart.

4. Ask Claude anything

"What's Polymarket saying about the next Fed decision? If 'hold' is above 70%, put $2 on it."

Claude reads the odds with blockrun_markets and — with your confirmation — places the trade with blockrun_polymarket. One wallet. Gasless. Confirm-gated.

Demo

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

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

(via blockrun_markets · cost: $0.0095)

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…)

Tools

Key use cases

1. Prediction-market consensus → "Polymarket's odds for the next Fed decision?" — blockrun_markets
2. Signal → trade (the full loop, self-custody) → "If 'hold' is under 30%, put $2 on Yes." — blockrun_markets reads, blockrun_polymarket action:"buy" places. Gasless, confirm-gated.
3. On-chain forensics → "This wallet — what's it labeled, what does it hold, when did it whale up?" — blockrun_surf
4. Cited research → "5 most-cited papers on speculative decoding, last 90 days." — blockrun_exa
5. Image generation with on-image text → "Poster announcing GPT-5.5, retro-futuristic, headline 'NOW LIVE'." — blockrun_image
6. Give your agent a voice → "Speak this with the sarah voice." — blockrun_speech
7. Voice phone-out → "Call +1-415-… and confirm Friday at 3pm." — blockrun_phone
8. Multi-agent research, capped → "Spawn 3 agents on competing L1 narratives. Cap each at $0.50." — blockrun_wallet delegate × 3
9. Cross-chain SQL → "Top 10 tokens by DEX volume on Base, last 24h." — blockrun_surf onchain/sql

📈 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 — 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 smart-contract vault on Polygon, CREATE2-derived from your key (only your key can authorize it), holds betting funds in pUSD (Polymarket's 1:1 collateral wrapper). Deployment, approvals, and redemptions all run gasless through Polymarket's relayer — you never need POL.

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

# 1. Provision your deposit wallet (idempotent, gasless)
blockrun_polymarket action:"setup"

# 2. Fund it from your Base USDC in one call (gasless; $0.01 fee, non-custodial)
blockrun_polymarket action:"fund" amount_usd:5 confirm:true

# 3. Sign the one-time gasless approval batch
blockrun_polymarket action:"setup" confirm:true

# 4. Find a market, preview safely, then place only after exact user approval
blockrun_polymarket_read action:"preview" side:"buy" token_id:"<id>" amount_usd:5 order_type:"FOK"
blockrun_polymarket action:"buy" token_id:"<id>" amount_usd:5 order_type:"FOK" confirm:true

# 5. Manage → positions · orders · cancel · sell · redeem · withdraw

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 + many regions). Handled by default — the MCP routes CLOB traffic through BlockRun's hosted Finland egress (a fully unrestricted region under Polymarket's policy), so trading works out of the box; setup reports your status. Override POLYMARKET_CLOB_HOST to go direct or run your own egress, optionally reached via HTTPS_PROXY / POLYMARKET_CLOB_PROXY (a proxy alone doesn't change the Polymarket-facing egress). Complying with Polymarket's terms for your jurisdiction is your responsibility.

⚠️ Back up your signer key (~/.blockrun/.session by default; a BLOCKRUN_WALLET_KEY env var or an existing agent wallet.json takes precedence — setup prints the actual signer address). It is the only key to both the payment wallet and the Polymarket deposit wallet.

Fund your wallet

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

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

Pay on Solana

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 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: blockrun_music, blockrun_speech, blockrun_video, paid blockrun_realface, paid stock blockrun_price, and native Anthropic (claude-*) passthrough. In Solana mode they return a "switch to Base" message instead of charging. blockrun_image pays on either chain.

For agents & LLMs

If you are an LLM invoking BlockRun MCP tools, read these first:

• CRITICAL: On any payment / balance / 402 error, call blockrun_wallet first to check status, then action:"setup" for funding. Don't retry the failing tool blindly — the wallet is empty.
• CRITICAL: blockrun_polymarket moves REAL user funds (pUSD on Polygon), separate from the x402 API budget. Never buy/sell/redeem with confirm:true unless the user explicitly approved that exact trade; without confirm you get a safe dry-run. Discover markets/token IDs with blockrun_markets first.
• CRITICAL: blockrun_surf's 84-endpoint catalog is in skills/surf/SKILL.md; blockrun_markets' full endpoint list is in its tool description (worked examples in skills/prediction-markets/SKILL.md; live-demo workflow in skills/signal-to-trade-demo/SKILL.md). Browse those before guessing paths.
• CRITICAL: blockrun_music and blockrun_video are payment-on-completion async. Failures / client timeouts do NOT charge. Don't retry-loop — 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, then pass agent_id:"X" to every downstream call. The child is auto-blocked at zero.
• Free tier first for drafts: blockrun_chat mode:"free" (NVIDIA), blockrun_dex, blockrun_price (crypto/FX/commodity), and blockrun_models are $0.

Showcase

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

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

Why not just use the APIs directly?

One wallet. All sources. No dashboards.

Configuration

Chain selection priority (src/utils/wallet.ts): .chain preference → SOLANA_WALLET_KEY → .solana-session exists → otherwise Base.

The server runs a non-blocking npm registry check at startup and prints an Update available notice to stderr when a newer @blockrun/mcp exists — re-run the install command to upgrade.

Troubleshooting

• Insufficient balance / HTTP 402 after retry → Run blockrun_wallet action:"setup", send USDC on Base (or Solana).
• blockrun doesn't connect / "MCP server failed" / spawn npx ENOENT → Almost always a PATH issue: Claude Code can't find node/npx on its launcher PATH (common with Homebrew / nvm, on CLI and desktop). Fix by passing your shell PATH at install:
  bash

  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 pin absolute paths (which npx).
• claude mcp list doesn't show blockrun → Check node -v (≥20.19). Clear the npx cache: rm -rf ~/.npm/_npx. Re-run the install.
• fetch failed / balance-check timeout → Base RPC transient outage. The tool falls through 3 public RPCs; retry after 30s. Persistent = local proxy / firewall blocking outbound RPC.
• Video/Music generation timed out → Upstream queue congestion. No charge (payment-on-completion). Retry, or pick a faster model.
• Polymarket: neg-risk ("winner") market buy fails, or redeem reverts, though setup shows ready → Re-run action:"setup" confirm:true once (grants the on-chain approvals a pre-upgrade deposit wallet may lack — including the collateral-adapter approvals redeem needs). See the setup guide.

FAQ

What is BlockRun MCP? An open-source MCP server that gives Claude and other agents <!-- br:mcp.tools -->20<!-- /br:mcp.tools --> tools for real-time data and real actions (trading, media, on-chain), paid per call in USDC. No accounts, no API keys.

Do I need API keys or accounts? No. A wallet is auto-created locally on first run; you fund it with USDC. No signups, no dashboards, no key rotation.

How much does it cost? Pay-per-call — fractions of a cent to a few cents. The free tier (blockrun_chat mode:"free", blockrun_dex, crypto blockrun_price, blockrun_models) is $0. $5 of USDC covers thousands of queries.

Is it safe / non-custodial? Yes. Your private key never leaves your machine (~/.blockrun/.session by default, 0600). x402 payments and Polymarket orders are signed locally — BlockRun forwards signed payloads and cannot move your funds.

Which clients work? Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

Can it really place real bets? Yes. blockrun_polymarket places real, USDC-settled orders on Polymarket's CLOB — confirm-gated and capped. Read the odds with blockrun_markets, place with blockrun_polymarket.

Base or Solana? Both. Switch instantly with blockrun_wallet action:"chain". A few media/paid tools settle on Base only (noted above).

From the BlockRun ecosystem

BlockRun is agent-native AI infrastructure — one wallet, x402 USDC micropayments, across every surface:

• ⚡ ClawRouter — the agent-native LLM router for OpenClaw. <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible --> models, <1ms local routing, USDC on Base & Solana.
• 🤖 BRCC — BlockRun for Claude Code: smart routing + x402 payments, purpose-built for Claude Code.
• 🐍 ClawRouter-Hermes — Python plugin wiring NousResearch Hermes into the ClawRouter proxy.
• 📚 Docs · Models & pricing — full SDKs, APIs, and the model catalogue.

Support & community

Contributing

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

MIT License · blockrun.ai — Agent-native AI infrastructure

Website · npm · Docs · @BlockRunAI