Bitcoin MCP Server — Connect AI Agents to Your Node in 60 Seconds

bitcoin-mcp is the open-source MCP server for Bitcoin Core. Give Claude, Cursor, Windsurf, or any AI agent direct tool-call access to 73 Bitcoin endpoints — fees, blocks, mempool, mining, transactions, and more.

Get Started View on GitHub

Setup in 3 Steps

From zero to AI-powered Bitcoin queries in under 60 seconds.

Install bitcoin-mcp

One pip install. That's it. bitcoin-mcp includes everything needed to bridge your AI agent to Bitcoin.

$ pip install bitcoin-mcp

If you're running your own node, also install the API:

$ pip install satoshi-api
$ export BITCOIN_RPC_USER=your_user
$ export BITCOIN_RPC_PASSWORD=your_password
$ satoshi-api

Configure your AI client

Add the MCP server to your client's config. Here's Claude Desktop:

// claude_desktop_config.json
{
  "mcpServers": {
    "bitcoin": {
      "command": "bitcoin-mcp",
      "env": {"SATOSHI_API_URL": "http://localhost:9332"}
    }
  }
}

No node? Point at the hosted endpoint instead:

"env": {"SATOSHI_API_URL": "https://bitcoinsapi.com"}

Ask a question

Open your AI client and ask anything about Bitcoin. The agent automatically calls the right tool.

You: What are the current Bitcoin fees? Should I send now or wait?

Claude: Let me check the current fee environment.
[Calling get_recommended_fees...]
[Calling get_fee_landscape...]

Current fees are 12 sat/vB for high priority. The mempool is
clearing steadily — good time to send at medium priority (8 sat/vB)
for confirmation within ~30 minutes.

What Can Your Agent Do?

Real questions mapped to the tools bitcoin-mcp exposes.

"What are current Bitcoin fees?"
Returns fee estimates in sat/vB for high, medium, and low priority with a human-readable recommendation.
get_recommended_fees
"Should I send now or wait?"
Analyzes mempool congestion, fee trends, and recent block rates to produce a send-now-or-wait recommendation.
get_fee_landscape
"What's in the latest block?"
Returns block height, tx count, total fees, weight utilization, miner, and time since the previous block.
get_latest_block
"Is the mempool congested?"
Returns congestion level, transaction count, total size in vMB, fee distribution buckets, and minimum fee for the next block.
get_mempool
"When is the next difficulty adjustment?"
Returns current difficulty, estimated hashrate, blocks until retarget, and projected adjustment percentage.
get_mining_stats
"How much would a 2-in, 1-out tx cost?"
Returns estimated transaction size in vBytes and cost at each fee priority level for the given input/output configuration.
estimate_transaction_fee

Configuration for Every Client

bitcoin-mcp works with any MCP-compatible AI client. Pick yours.

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "bitcoin": {
      "command": "bitcoin-mcp",
      "env": {"SATOSHI_API_URL": "http://localhost:9332"}
    }
  }
}

Config file location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Add via the CLI or edit .claude/settings.json:

$ claude mcp add bitcoin -e SATOSHI_API_URL=http://localhost:9332 -- bitcoin-mcp

Or add manually to .claude/settings.json:

{
  "mcpServers": {
    "bitcoin": {
      "command": "bitcoin-mcp",
      "env": {"SATOSHI_API_URL": "http://localhost:9332"}
    }
  }
}

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "bitcoin": {
      "command": "bitcoin-mcp",
      "env": {"SATOSHI_API_URL": "http://localhost:9332"}
    }
  }
}

Restart Cursor after adding the config. The Bitcoin tools will appear in the MCP tools panel.

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "bitcoin": {
      "command": "bitcoin-mcp",
      "env": {"SATOSHI_API_URL": "http://localhost:9332"}
    }
  }
}

Restart Windsurf after saving. The Bitcoin tools will be available in Cascade.

No node? No problem.

Replace http://localhost:9332 with https://bitcoinsapi.com in any config above to use the hosted API. No Bitcoin Core installation required. For authenticated access to POST endpoints, add "--api-key", "your_key" to the args array.

Environment Variables Reference

All configuration options for bitcoin-mcp and Satoshi API.

bitcoin-mcp

VariableDescriptionDefault
BITCOIN_MCP_API_URLSatoshi API base URLhttp://localhost:9332
BITCOIN_MCP_API_KEYAPI key for authenticated endpointsNone (anonymous)
BITCOIN_MCP_TIMEOUTRequest timeout in seconds30

Satoshi API (if self-hosting)

VariableDescriptionDefault
BITCOIN_RPC_USERBitcoin Core RPC usernameRequired
BITCOIN_RPC_PASSWORDBitcoin Core RPC passwordRequired
BITCOIN_RPC_HOSTBitcoin Core RPC host127.0.0.1
BITCOIN_RPC_PORTBitcoin Core RPC port8332
SATOSHI_API_PORTPort Satoshi API listens on9332
SATOSHI_API_KEYAPI key for authenticated accessNone (anonymous only)

Frequently Asked Questions

Common questions about bitcoin-mcp and Bitcoin + AI integration.

How do I connect Claude to Bitcoin?
Install bitcoin-mcp (pip install bitcoin-mcp), add it to your Claude Desktop or Claude Code config, and point it at a Satoshi API instance — either your own node at localhost:9332 or the hosted endpoint at bitcoinsapi.com. Claude will automatically discover the Bitcoin tools and can query fees, blocks, mempool, mining data, and more during any conversation.
What is bitcoin-mcp?
bitcoin-mcp is an open-source MCP (Model Context Protocol) server that wraps Satoshi API's 73 Bitcoin endpoints as AI tool calls. It's the bridge between AI agents and Bitcoin blockchain data. Install it with pip install bitcoin-mcp and configure your AI client to use it. Source code: github.com/Bortlesboat/bitcoin-mcp.
Can I use bitcoin-mcp without running a full node?
Yes. Point bitcoin-mcp at the hosted Satoshi API endpoint (https://bitcoinsapi.com) instead of localhost:9332. You get instant access to all 74 endpoints with no node setup. For maximum privacy and sovereignty, self-hosting with your own Bitcoin Core node is recommended — but it's not required to get started.
What AI agents work with bitcoin-mcp?
Any MCP-compatible client works: Claude Desktop, Claude Code (CLI), Cursor, Windsurf, and custom agents built on the MCP protocol. See the configuration section above for JSON configs for each client. The MCP standard is growing — as more clients adopt it, bitcoin-mcp will work with them automatically.
Is it safe to connect an AI agent to my Bitcoin node?
Yes. bitcoin-mcp connects through Satoshi API, which provides a read-only REST layer over your node by default. The AI agent never touches your node's RPC directly. Satoshi API includes rate limiting, input validation, and API key authentication. POST endpoints (like transaction broadcast) require explicit API key authorization. Self-hosting means no third party ever sees your queries.

Related Pages

Why AI Agents Need Bitcoin Data
The case for giving LLMs direct access to real-time blockchain data via MCP.
Fee API Endpoints
Multi-target fee estimation, congestion scoring, and fee landscape analysis.
Mempool API Endpoints
Real-time mempool analysis, distribution buckets, and transaction monitoring.
Self-Hosting Guide
Run Satoshi API on your own Bitcoin Core node for maximum privacy and control.

Connect your AI agent to Bitcoin.

One pip install. One JSON config. 74 endpoints at your agent's fingertips.

Get bitcoin-mcp View on PyPI