@blockrun/mcp

Access 30+ AI models in Claude Code with zero API keys.

One wallet. Pay-per-request. All major AI models.

claude mcp add blockrun npx @blockrun/mcp

Why BlockRun MCP?

Quick Start

1. Install (30 seconds)

# Add to Claude Code
claude mcp add blockrun npx @blockrun/mcp

That's it! A wallet is automatically created for you.

2. Get Your Wallet Address

In Claude Code, run:

Use blockrun_setup to get my wallet address

Or:

Use blockrun_wallet to show my wallet info

3. Fund Your Wallet

Send USDC to your wallet address on Base network. Even $5 gets you hundreds of requests.

Funding Options:

4. Start Using

You: Use blockrun_chat to ask claude-sonnet-4 what is quantum computing

Claude: [calls blockrun_chat]
        Quantum computing is a type of computation that harnesses...

Available Tools

blockrun_chat

Chat with any AI model.

blockrun_chat({
  model: "anthropic/claude-sonnet-4",  // Required
  message: "Explain quantum computing", // Required
  system: "You are a physics professor", // Optional
  max_tokens: 2000,                      // Optional (default: 1024)
  temperature: 0.7                       // Optional (default: 1)
})

Popular Models:

• openai/gpt-5.2 - Most capable OpenAI model
• anthropic/claude-opus-4 - Best for complex reasoning
• anthropic/claude-sonnet-4 - Fast & capable (recommended)
• google/gemini-2.5-pro - Great for long context (1M tokens)
• deepseek/deepseek-chat - Very affordable

blockrun_smart

Auto-select the best model for your needs.

blockrun_smart({
  mode: "balanced",  // Required: fast | balanced | powerful | cheap | reasoning
  message: "Hello!"  // Required
})

blockrun_models

List all available models with pricing.

blockrun_models({
  category: "chat",    // Optional: all, chat, reasoning, image, embedding
  provider: "openai"   // Optional: filter by provider
})

blockrun_image

Generate images with AI.

blockrun_image({
  prompt: "A sunset over mountains",  // Required
  model: "openai/dall-e-3",           // Optional
  size: "1024x1024",                  // Optional: 1024x1024, 1792x1024, 1024x1792
  quality: "hd"                       // Optional: standard, hd
})

blockrun_wallet

Check your wallet information.

blockrun_wallet({})
// Returns: address, network, balance link, funding options

blockrun_setup

Get detailed setup and funding instructions.

blockrun_setup({})
// Returns: complete setup guide with step-by-step funding instructions

Supported Models & Pricing

Chat Models

M = million tokens. Prices in USD.

Image Models

Cost Examples

$5 gets you approximately:

• 50,000 Gemini Flash requests, OR
• 1,600 Claude Sonnet requests, OR
• 1,000 GPT-4o requests, OR
• 125 DALL-E 3 images

Wallet Management

Auto-Generated Wallet

When you first use BlockRun MCP, a wallet is automatically created and saved to:

~/.blockrun/.session

This wallet is:

• Created locally on your machine
• Never transmitted to any server
• Used only for signing payment authorizations
• Persistent across sessions

Using Your Own Wallet

If you prefer to use an existing wallet:

# Option 1: Environment variable
export BLOCKRUN_WALLET_KEY=0x...

# Option 2: Add with Claude Code
claude mcp add blockrun npx @blockrun/mcp --env BLOCKRUN_WALLET_KEY=0x...

Wallet Priority

1. Environment variable BLOCKRUN_WALLET_KEY
2. Environment variable BASE_CHAIN_WALLET_KEY
3. File at ~/.blockrun/.session
4. Auto-generate new wallet (saved to file)

How Payment Works

┌─────────────────────────────────────────────────────────────┐
│  1. You send a request (e.g., chat with GPT-5)              │
│                          ↓                                  │
│  2. BlockRun calculates cost based on tokens                │
│                          ↓                                  │
│  3. Your wallet signs a payment authorization LOCALLY       │
│     (private key NEVER leaves your machine)                 │
│                          ↓                                  │
│  4. Payment settles on Base network via USDC                │
│                          ↓                                  │
│  5. You receive your AI response                            │
└─────────────────────────────────────────────────────────────┘

Security Guarantees:

• Private key is used ONLY for local signing
• Key is NEVER transmitted to any server
• Same security model as MetaMask transactions
• You can verify all transactions on Basescan

Comparison with Alternatives

vs claude-code-proxy

vs gemini-mcp

vs Direct API Keys

Troubleshooting

"Payment was rejected"

Your wallet needs funding. Run blockrun_setup to get your address and funding instructions.

"Wallet key required"

The MCP couldn't find or create a wallet. Check that ~/.blockrun/ directory is writable.

Model not responding

Some models have rate limits. Try blockrun_smart with mode fast or cheap to use alternative models.

Check wallet balance

Visit: https://basescan.org/address/YOUR_ADDRESS

Configuration

Claude Code Setup

# Basic (recommended)
claude mcp add blockrun npx @blockrun/mcp

# With explicit wallet
claude mcp add blockrun npx @blockrun/mcp --env BLOCKRUN_WALLET_KEY=0x...

# Project-specific
claude mcp add blockrun --scope project npx @blockrun/mcp

# User-wide (all projects)
claude mcp add blockrun --scope user npx @blockrun/mcp

Environment Variables

Development

# Clone
git clone https://github.com/blockrunai/blockrun-mcp
cd blockrun-mcp

# Install dependencies
npm install

# Development mode (auto-reload)
npm run dev

# Build for production
npm run build

# Test locally
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js

Links

• Website: blockrun.ai
• Documentation: docs.blockrun.ai
• Pricing: blockrun.ai/pricing
• GitHub: github.com/blockrunai
• Twitter: @blockaborama

Support

• Issues: GitHub Issues
• Discord: Join our Discord
• Email: hello@blockrun.ai

License

MIT