MCP Mempool Server

You set up a dedicated MCP server to expose mempool.space data through a streamlined API and WebSocket interface, enabling AI agents and external apps to access real-time Bitcoin network information and queries with minimal friction.

How to use

You can access real-time mempool and network data by running the server locally or in a container, then connect your MCP client to the provided endpoints. The WebSocket stream delivers live blocks, mempool templates, stats, address tracking, and live fee charts. The REST API provides address details, transactions, blocks, fees, mempool status, and address validation. Use the HTTP endpoint for MCP requests or connect through the local stdio-based runtime if you prefer embedding the server in your tooling.

How to install

Prerequisites: you need a runtime that can execute the MCP server and a way to obtain dependencies.

# Development environment setup (example)
docker-compose up mcp-mempool-dev

Configuration and start

Choose your run mode and start the server. You can run locally with the runtime command or pull a prepared container for production.

# Local startup using the runtime shell
uv run python -m mempool_ws_mcp_server.main

# HTTP MCP server endpoint (remote connection)
# This is the MCP URL you would use from a client
http://localhost:8000/mcp

Configuration reference

The server exposes several environment settings to tailor its behavior. Configure host, port, and API endpoints to match your deployment requirements.

# Server settings
MCP_HOST=0.0.0.0
MCP_PORT=8000
LOG_LEVEL=INFO

# Mempool API sources
MEMPOOL_WS_URL=wss://mempool.space/api/v1/ws
MEMPOOL_API_URL=https://mempool.space/api

# WebSocket keepalive
WS_RECONNECT_INTERVAL=5
WS_MAX_RECONNECT_ATTEMPTS=10
WS_PING_INTERVAL=30
WS_PING_TIMEOUT=10

# HTTP client behavior
HTTP_TIMEOUT=30
HTTP_MAX_RETRIES=3

# Performance
MAX_MESSAGE_QUEUE_SIZE=1000
MESSAGE_BATCH_SIZE=10

# Security
CORS_ENABLED=true
ALLOWED_ORIGINS=* 

# Development mode
DEBUG=false
RELOAD=false

Usage examples

These concrete patterns show how you typically query data and observe live updates from the MCP server.

# Check balance for an address
get_address_balance address="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"

# Subscribe to real-time mempool blocks
subscribe_mempool_blocks

# Get recommended fees
get_recommended_fees

# Track a specific address in real time
track_address address="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"

Available tools

subscribe_blocks

Subscribe to live block notifications when new blocks are created.

subscribe_mempool_blocks

Receive real-time information about the next block template.

subscribe_stats

Monitor mempool and network statistics in real time.

subscribe_live_chart

Get a live 2-hour chart of fee changes.

track_address

Track transactions for a specific Bitcoin address in real time.

get_connection_status

Check the status of the WebSocket connection.

unsubscribe_client

Unsubscribe a client from all subscriptions using their client ID.

get_address_info

Query complete information for a Bitcoin address, including balance, UTXOs, and transactions.

get_address_balance

Query the balance for a Bitcoin address.

get_address_utxos

Query the UTXO set for a Bitcoin address.

get_address_transactions

Query transactions related to a Bitcoin address.

get_transaction_info

Query detailed information about a specific transaction.

get_block_info

Query information about a block by hash or height.

get_block_height

Query the current block height.

get_recommended_fees

Query recommended fee rates for different confirmation targets.

get_mempool_info

Query current mempool state and recent transactions.

validate_bitcoin_address

Validate whether a given string is a valid Bitcoin address.