A Model Context Protocol (MCP) server that provides real-time Bitcoin blockchain data by querying the mempool.space API.

This MCP server offers five specialized tools for querying Bitcoin blockchain data:

Get basic statistics for any Bitcoin address.

Input:

• address (string): Bitcoin address to query

Output:

• Chain statistics (funded/spent amounts, transaction counts)
• Mempool statistics (pending transactions)

Example:

Address: 1wiz18xYmhRX6xStj2b9t1rwWX4GKUgpv

Chain Stats:
- Funded TXOs: 10
- Funded Sum: 150.07686949 BTC
- Spent TXOs: 5
- Spent Sum: 150.07599040 BTC
- Total Transactions: 12

Mempool Stats:
- Pending TXOs: 0
- Pending Sum: 0.00000000 BTC
- Pending Transactions: 0

Get transaction history for a Bitcoin address.

Input:

• address (string): Bitcoin address to query
• limit (optional, number): Number of transactions to return (1-50, default: 10)

Output:

• List of recent transactions with status, dates, fees, and sizes

Get current UTXOs (unspent transaction outputs) for a Bitcoin address.

Input:

• address (string): Bitcoin address to query
• limit (optional, number): Number of UTXOs to return (1-50, default: 10)

Output:

• List of current UTXOs with amounts, confirmation status, and dates

Get detailed information about a specific Bitcoin transaction.

Input:

• txid (string): Transaction ID (hash) to query

Output:

• Complete transaction details including:
  • Basic info (version, size, weight, fee)
  • Confirmation status and block information
  • Input and output details with amounts and addresses

Get information about a specific Bitcoin block.

Input:

• block_height (number): Block height to query

Output:

• Block details including:
  • Hash, version, merkle root
  • Previous block hash and timestamp
  • Size, weight, and transaction count
  • Fee statistics

1. Install the package globally:

npm install -g @jamesanz/bitcoin-mcp

2. Run the automated setup script:

# For Claude Desktop
npx @jamesanz/bitcoin-mcp setup claude

# Or show manual instructions
npx @jamesanz/bitcoin-mcp setup manual

3. Restart your MCP client (e.g., Claude Desktop)

If the automated setup doesn't work, you can configure manually:

1. Install the package:

npm install -g @jamesanz/bitcoin-mcp

2. Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bitcoin-mcp": {
      "command": "npx",
      "args": ["@jamesanz/bitcoin-mcp"]
    }
  }
}

3. Restart Claude Desktop

1. Install the package:

npm install -g @jamesanz/bitcoin-mcp

2. Configure your MCP client to use:

   • Command: npx
   • Args: ["@jamesanz/bitcoin-mcp"]

3. Restart your MCP client

If you want to run from source:

1. Clone this repository:

git clone https://github.com/JamesANZ/bitcoin-mcp.git
cd bitcoin-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Run the setup script:

npm run setup claude

Start the MCP server:

npm start

The server runs on stdio and can be connected to any MCP-compatible client.

Here are some example queries you can make with this MCP server:

{
  "tool": "get-address-stats",
  "arguments": {
    "address": "1wiz18xYmhRX6xStj2b9t1rwWX4GKUgpv"
  }
}

{
  "tool": "get-address-transactions",
  "arguments": {
    "address": "1wiz18xYmhRX6xStj2b9t1rwWX4GKUgpv",
    "limit": 5
  }
}

{
  "tool": "get-transaction",
  "arguments": {
    "txid": "15e10745f15593a899cef391191bdd3d7c12412cc4696b7bcb669d0feadc8521"
  }
}

{
  "tool": "get-block",
  "arguments": {
    "block_height": 857808
  }
}

This MCP server uses the following mempool.space API endpoints:

• GET /api/address/{address} - Address statistics
• GET /api/address/{address}/txs - Address transaction history
• GET /api/address/{address}/utxo - Address UTXOs
• GET /api/tx/{txid} - Transaction details
• GET /api/block/{height} - Block information

All amounts are displayed in BTC (converted from satoshis) for better readability. Timestamps are converted to ISO format for easy parsing.

The server includes comprehensive error handling:

• Network errors are caught and reported with descriptive messages
• Invalid addresses or transaction IDs return appropriate error messages
• Rate limiting and API errors are handled gracefully

• @modelcontextprotocol/sdk - MCP SDK for server implementation
• superagent - HTTP client for API requests
• zod - Schema validation for tool parameters

This project is licensed under the MIT License - see the LICENSE.md file for details.