blockrun-mcp

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 — 20 tools for real-time data and real actions: 71 LLMs, image & video generation, prediction-market data, live web/X search, on-chain queries across 40 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 — 20 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.
• Human-in-the-loop payments — turn on `BLOCKRUN_CONFIRM_SPEND=on` and the agent pauses before any paid call above your threshold; nothing is signed until you approve. Details ↓
• Generative UI — on Claude Desktop, claude.ai, VS Code and Cursor the Polymarket preview is a live order card with a Place button, and the wallet is a panel with balances, QR and card top-up. MCP Apps ↓
• Self-custody — your key never leaves your machine (`~/.blockrun/.session`, `0600` — or the OS keychain once you opt into `BLOCKRUN_KEYCHAIN=strict`). 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.

Every MCP client — one command or one JSON block. *Verified* = we ran the published package on that client and saw the tools listed (client version · date). *Documented* = install path from the client's own docs; not run by us yet — tell us if it works. The Spend dialog column is whether the client renders the human-in-the-loop payment prompt; on ❌ clients paid calls proceed without asking and `BLOCKRUN_BUDGET_LIMIT` is the guard.

Any other MCP client that can spawn a stdio server works the same way: `command: npx`, `args: ["-y", "@blockrun/mcp@latest"]`. With nvm/Homebrew Node on a JSON-configured client, put the absolute path from `which npx` in `command`. Spend-dialog sources and what "proceeds without asking" means: `docs/spend-confirmation.md`.

JSON for Claude Desktop, Cursor, Windsurf

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

Add `"env": { "BLOCKRUN_CONFIRM_SPEND": "on" }` inside the server object to turn on the spend dialog where the client supports it.

2. Choose a tool profile (optional)

Expose a trimmed tool set so the client loads fewer schemas into context. Pass `--profile ` (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.

What each profile costs your context

Installing an MCP server spends context on every turn, whether or not you call the tools —

the client loads each tool's schema into the model's prompt and re-sends it for the whole session.

Package managers have shown install size for decades. Almost no MCP server shows this. Ours:

Running `--profile trading` instead of the default costs 57% less context for the same trading

workflow. If you only ever ask about markets, that is the single cheapest change you can make.

Measure it yourself — against us, or against any other stdio MCP server:

npm i gpt-tokenizer
node scripts/measure-tool-schema.mjs                     # this server, every profile
node scripts/measure-tool-schema.mjs -- npx -y @some/other-mcp-server

How the number is computed, and why it is a slight under-count

It counts the model-visible projection — `{name, description, input_schema}` per tool, with the

`mcp__blockrun__` prefix the host prepends — because that is what lands in the API `tools` array.

It excludes `annotations`, `_meta` and `outputSchema`, which the host consumes and never forwards

to the model (a further ~3.7% on the wire).

The tokenizer is `o200k_base`. Claude's tokenizer is not public and runs a few percent higher on

JSON, so every figure here is a slight under-count, never an over-count.

Two caveats worth stating plainly. Tool schemas sit at the front of the prompt and are covered by

prompt caching, so after the first turn they re-send at cache-read rates — the *context-window*

cost is 100% every turn, the *dollar* cost is roughly a tenth of that. And 54% of our own cost is

tool descriptions, not schemas, which is where the remaining work is.

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 · ~14 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.

5. Install the agent skills (optional)

The package ships 16 skills — which tool answers what, worked examples, and a setup / debug / upgrade trio so the agent can install, troubleshoot and update the server on its own.

/plugin marketplace add BlockRunAI/blockrun-mcp            # Claude Code
npx -y @blockrun/mcp@latest skills install                 # any project → ./.claude/skills
npx -y @blockrun/mcp@latest skills install --global        # ~/.claude/skills
npx -y @blockrun/mcp@latest skills install --to ~/.codex/skills

`skills list` shows what ships; `--only a,b` picks; `--force` refreshes copies after an upgrade.

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:"" amount_usd:5 order_type:"FOK"
blockrun_polymarket action:"buy" token_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.

🛡️ Human-in-the-loop payments

Turn on `BLOCKRUN_CONFIRM_SPEND=on` and every paid tool pauses before it signs. The server sends an MCP elicitation; your client renders it as a dialog with the estimated charge:

💸 BlockRun charge — video · bytedance/seedance-2.5 · 10s
Estimated: $2.6500
Approve this spend? (USDC is debited per call.)
To stop the charge, choose Decline — Cancel/ESC lets it proceed.

[ ] Approve all BlockRun charges for the rest of this session (don't ask again)

                                          [ Decline ]  [ Approve ]

Decline → nothing is sent, nothing is charged, the tool reports *"Charge declined"*. Approve → the call proceeds. Tick the box and you're not asked again for the session. Free calls never prompt. Set `BLOCKRUN_CONFIRM_THRESHOLD=0.05` to only be asked above $0.05.

claude mcp add blockrun -s user -e BLOCKRUN_CONFIRM_SPEND=on -e BLOCKRUN_CONFIRM_THRESHOLD=0.05 -- npx -y @blockrun/mcp@latest

On a client that can't ask, the gate fails open — the call proceeds and the cost footer reports the charge. The hard stop on every client is the budget: `BLOCKRUN_BUDGET_LIMIT` for the process, `blockrun_wallet action:"delegate"` per sub-agent. `blockrun_polymarket` keeps its own, stronger per-order `confirm:true`.

📖 When to use it, sources for the matrix, limitations: `docs/spend-confirmation.md`

🧩 MCP Apps — order card & wallet panel

On hosts that support the MCP Apps extension — Claude Desktop, claude.ai, VS Code, Cursor, ChatGPT — two tools render as interactive cards instead of text. Everywhere else (Claude Code, Codex, terminals) nothing changes.

   

• Order card on `blockrun_polymarket_read action:"preview"` — question, outcome, side, best quote, est. shares, notional, cap meter, session ledger. Edit the amount → Re-quote. Place order is arm-then-confirm and asks the *host* to call `blockrun_polymarket … confirm:true`, so the host's consent prompt and every server cap (`POLYMARKET_MAX_BET_USD`, session cap) still apply.
• Wallet panel on `blockrun_wallet` — both chains' balances, switch chain, copy address, EIP-681 / Solana Pay QR, explorer, Buy USDC with card.

📖 Hosts, money path, local testing: `docs/mcp-apps.md`

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 ~14 Seedance 1.5-pro clips (5s @ 720p+audio, ~$0.35 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_modal`, `blockrun_defi`, 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` and `blockrun_video` pay 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.
• A declined spend confirmation is the user's decision. Report it and stop — never re-issue the call with a cheaper model, smaller parameters, or split requests to get under their threshold.

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

Environment variables & files

Chain selection priority (`src/utils/wallet.ts`): `.chain` preference → `SOLANA_WALLET_KEY` → `.chain-auto` pin → `.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

> 🤖 Hand this to the agent: the `blockrun-debug` skill carries every row below as symptom → cause → fix, plus the diagnostics it can run itself. `blockrun-setup` and `blockrun-upgrade` cover the other two halves. Install: `npx -y @blockrun/mcp@latest skills install`.

• `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:

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.
• No spend-confirmation dialog although `BLOCKRUN_CONFIRM_SPEND=on` → Your client doesn't support MCP elicitation (Windsurf, Codex, Gemini CLI); the server proceeds without asking by design. Use `BLOCKRUN_BUDGET_LIMIT` as the guard, or a client from the support table.
• 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 20 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?

Any MCP client that can spawn a stdio server. Verified on Claude Code and Codex CLI, in daily use on OpenClaw; install paths documented for Claude Desktop, Cursor, VS Code, Gemini CLI and Windsurf — see the client table. The spend-confirmation dialog additionally needs MCP elicitation (Claude Code, Cursor, VS Code).

Does it have a UI?

On MCP-Apps hosts (Claude Desktop, claude.ai, VS Code, Cursor) the Polymarket preview is a live order card and the wallet is a panel — see MCP Apps ↑. Terminal clients get the same information as text.

Can I make the agent ask before it spends?

Yes — `BLOCKRUN_CONFIRM_SPEND=on`. Every paid tool pauses with the estimated charge and nothing is signed until you approve. Human-in-the-loop payments ↑

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. 71 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.