BlockRunAI/blockrun-mcp

BlockRun MCP – A Pay‑per‑call data & action server for AI agents

What it is

• An open‑source Model Context Protocol (MCP) server written in TypeScript/Node that plugs into any MCP‑compatible LLM agent (Claude, Codex, Cursor, VS Code, etc.).
• It exposes 19 ready‑to‑use tools such as:
  • Real‑time market data and the ability to place real USDC‑settled bets on Polymarket.
  • Web, X (formerly Twitter), and scholarly search.
  • Image, video, and audio generation.
  • On‑chain queries across ≈40 blockchains (Solana, Base, etc.).
  • LLM model access, price feeds, DEX data, and more.
• The tools are agent‑native: an LLM can call them directly from its prompt without any human‑written glue code.

How you pay

• Wallet mode (default) – a self‑custody wallet is auto‑created on first run. You fund it with USDC on Solana or Base and each tool call is settled on‑chain via the x402 micropayment protocol (fractions of a cent plus a tiny network fee).
• API‑key mode – set BLOCKRUN_API_KEY (obtained from user.blockrun.ai) for teams that prefer a prepaid credit account instead of a wallet. Billing is exact‑usage, no per‑call fee.
• Both modes give the same 19 tools; you can switch at any time.

Why it matters for agents

• Traditional data APIs require a human to create accounts, store API keys, and manage credit‑card billing – steps an autonomous LLM cannot perform.
• BlockRun collapses all those sources behind a single authentication primitive (wallet signature or API key) and charges per call, enabling truly autonomous agents.
• It also supports human‑in‑the‑loop spend approval (BLOCKRUN_CONFIRM_SPEND=on) so a user can approve or reject any paid call that exceeds a budget.

Installation & usage

1. Install the MCP server (recommended via Claude Code):

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

   The command creates a wallet on first run; fund it with ~5 USDC or set an API key.
2. Choose a tool profile (optional) to reduce the amount of schema data loaded into the model’s context. Examples:
   • full – all 19 tools (default, ~12.6 K tokens of context per turn).
   • trading – 8 tools for market data and Polymarket trading (~5.2 K tokens).
   • media, research, chat – smaller subsets. Use --profile <name> or set BLOCKRUN_MCP_PROFILE.
3. Add funds
   • Wallet: send USDC to the address shown in ~/.blockrun/.session.
   • API key: obtain a key from the BlockRun dashboard and export it as BLOCKRUN_API_KEY.
4. Call tools from any MCP‑compatible client. Example (Claude):

   {"name":"blockrun_polymarket","input":{"question":"Will Bitcoin hit $100k this year?"}}
   

   The server returns live odds; with blockrun_polymarket you can also place a bet.

Supported clients (all can spawn the server via npx):

• Claude Code (verified), Codex CLI, OpenClaw, Claude Desktop, Cursor, VS Code Copilot, Gemini CLI, Grok, Windsurf, etc.
• Each client can be configured with a tiny JSON snippet that points to npx -y @blockrun/mcp@latest.

Key features

• One wallet, many sources – no per‑vendor sign‑ups.
• Pay‑per‑call in USDC via x402, or prepaid credit via API key.
• Read + act – tools not only fetch data but can execute real trades on Polymarket.
• Human‑in‑the‑loop spend dialogs to keep budgets safe.
• Generative UI – on Claude Desktop and VS Code the Polymarket tool shows an interactive order card; the wallet tool shows balances and QR codes.
• Open source MIT license – the server code is published on npm (@blockrun/mcp) and GitHub.

Who might use it

• Developers building autonomous agents that need live market, web, or blockchain data.
• Researchers experimenting with LLM‑driven trading or prediction‑market bots.
• Teams that want a unified, self‑custodied data layer for multiple agents without managing dozens of API keys.

---

Bottom line: BlockRun MCP turns an LLM into a fully‑fledged, financially‑capable agent by providing a single, pay‑per‑call gateway to 19 real‑time tools—including the ability to place actual USDC bets on Polymarket—while keeping authentication simple (wallet signature or API key) and costs transparent.