Skip to content

teamssUTXO/bitcoin_mcp

BranchesTags

Repository files navigation

Bitcoin MCP Server

A comprehensive Model Context Protocol (MCP) server that brings Bitcoin data and functionality directly to AI assistants like Claude, ChatGPT, and other MCP-compatible platforms.

For any questions send me a message on discord : teamsutxo

Bitcoin Bitcoin MCP License: MIT Python 3.12

📋 Table of Contents

🤖 What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. Think of it as a universal adapter that lets AI models interact with your applications, databases, and APIs in a standardized way.

Key Benefits of MCP

  • Plug-and-Play Integration: Connect AI assistants to external tools without custom code
  • Secure: Controlled access to data and operations
  • Universal: Works across different AI platforms (Claude, ChatGPT, etc.)
  • Modular: Easy to add, remove, or update capabilities

Learn more at modelcontextprotocol.io

💡 Why Use Bitcoin MCP Server?

The Bitcoin MCP Server empowers AI assistants with real-time Bitcoin data and analysis capabilities:

  • Real-time Data: Access current Bitcoin prices, market data, and network statistics
  • Blockchain Analysis: Query blocks, transactions, and addresses directly
  • Mining Insights: Get hashrate, difficulty, and mining pool information
  • Market Intelligence: Track price movements, volume, and market capitalization
  • Network Health: Monitor mempool status, fee estimates, and node statistics

No Bitcoin expertise required - just ask questions in natural language, and the AI handles the technical queries for you!

✨ Features

  • Network Overview: Real-time Bitcoin network statistics including hashrate, difficulty, block production, and transaction volume
  • Transaction Analysis: Detailed transaction information with input/output breakdown, fee analysis, and confirmation status
  • Address Intelligence: Complete address analytics including balance, transaction history and UTXO management
  • Block Explorer: Access to block data with mining pool information, transaction counts, fees, and timestamps
  • Market Data: Real-time Bitcoin price, market capitalization, trading volume, and multi-timeframe performance analysis
  • Mining Insights: Top mining pools ranking, hashrate distribution, network dominance statistics, and 3-month historical trends
  • Fee Recommendations: Dynamic fee estimates for different confirmation speeds (fastest, half-hour, standard, economy)
  • Market Sentiment: Community sentiment tracking and Fear & Greed Index with 7-day historical data
  • Trending Analytics: Discover trending cryptocurrencies, NFT collections, and categories

💼 Use Cases

For Investors & Traders

img

For Developers & Analysts

img

For Researchers & Educators

img

For Business Intelligence

img

You can use these examples :

  • Transaction : a1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d
  • Address : 1Ay8vMC7R1UbyCCZRVULMV7iQpHSAbguJP
  • Block (height) : 933135

🚀 Installation

Prerequisites

  • Python 3.12 installed on your system
  • UV package manager (obligatory)
  • An MCP-compatible AI client (e.g., Claude Desktop)

Option 1: Using UV (Recommended)

  1. Install UV (if not already installed) UV is a fast Python package installer and resolver.
  • Linux :
curl -LsSf https://astral.sh/uv/install.sh | sh
  • Windows :
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Restart your command-line window after installing this.

  1. Clone the repository:
git clone https://github.com/teamssUTXO/bitcoin_mcp.git
cd bitcoin_mcp
  1. Install dependencies:
uv venv
uv pip install -e .
  1. Install to Claude Desktop:
uv run mcp install src/main.py

Check How to configure MCP Server

Option 2: Using Python/Pip

  1. Clone the repository:
git clone https://github.com/teamssutxo/bitcoin_mcp.git
cd bitcoin_mcp
  1. Create a virtual environment (recommended):
python -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate
  1. Install dependencies:
pip install -r requirements.txt
  1. Run the server with Claude Desktop:

Follow the Claude configuration guide: : Config.README.md

Option 3: Using Docker

See README.Docker.md for detailed Docker deployment instructions.

Check server health

To check that the server is working correctly, use the endpoint /health.

Port Configuration

Customize the port with --port 8000 or -p 8000. Default: 3000.

🛠️ Available Tools

The Bitcoin MCP Server provides the following tools organized by category:

📬 Address Tools

  • get_address_overview
  • get_info_about_address

📦 Block Tools

  • get_10_latest_blocks_informations
  • get_block_hash_with_height
  • get_summary_of_latest_block

💸 Transaction Tools

  • get_bitcoin_transaction_infos
  • get_transaction_input_output
  • get_transactions_of_address

💰 Market Tools

  • get_bitcoin_price_usd
  • get_bitcoin_market_data
  • get_cryptomarket_overview
  • get_bitcoin_market_sentiment
  • get_trending_coins
  • get_trending_categories
  • get_trending_nfts

⛏️ Mining Tools

  • get_mining_pools_hashrates_3month
  • get_top_10_mining_pools_rank
  • get_bitcoin_network_mining_pools_statistics
  • get_top1_mining_pool
  • get_mining_pool_by_slugl

🌐 Network Tools

  • get_bitcoin_network_overview
  • get_bitcoin_network_recommended_fees
  • get_bitcoin_network_health

Total: 20+ tools and growing!

For detailed tool documentation, see the inline help in each tool module or use the MCP Inspector.

⚙️ Configuration

Quick Setup for Claude Desktop

After installation, configure Claude Desktop to use the Bitcoin MCP Server:

uv run mcp install src/main.py

This command automatically:

  • Detects your Claude Desktop installation
  • Creates the necessary configuration
  • Registers all Bitcoin tools

Then restart Claude Desktop to activate the server.

Manual Configuration for Claude Desktop

For detailed manual configuration instructions for Claude Desktop and other platforms, see how to configure MCP Server.

Configure the Server

You can customize the server behavior by editing the configuration file located at src/config.py.

Available Configuration Options

API Endpoints

  • MEMPOOL_API_URL: Mempool.space API endpoint (default: https://mempool.space/api)
  • COINGECKO_API_URL: CoinGecko API endpoint (default: https://api.coingecko.com/api/v3)
  • BLOCKCHAIN_INFO_API_URL: Blockchain.info API endpoint (default: https://blockchain.info)
  • HIRO_API_URL: Hiro API endpoint (default: https://api.hiro.so)
  • ALTERNATIVE_API_URL: Alternative.me API endpoint (default: https://api.alternative.me)

Bitcoin Constants

  • SATOSHI: Satoshi conversion factor (default: 100_000_000)

Performance & Reliability

  • ENABLE_CACHE: Enable response caching (default: True)
  • ENABLE_RETRY: Enable automatic retries on failures (default: True)
  • CACHE_TTL_TIME: Cache time-to-live in seconds (default: 60)
  • MAX_RETRIES: Maximum retry attempts for failed requests (default: 3)

Timeout Settings

  • API_CONNECT_TIMEOUT: Connection timeout in seconds (default: 5.0)
  • API_READ_TIMEOUT: Read timeout in seconds (default: 30.0)
  • API_WRITE_TIMEOUT: Write timeout in seconds (default: 10.0)
  • API_POOL_TIMEOUT: Connection pool timeout in seconds (default: 5.0)

Logging Configuration

  • LOGGER_NAME: Logger name (default: "bitcoin_mcp_server")
  • LOG_DIR: Directory for log files (default: "../logs")
  • LOG_LEVEL: Logging level - DEBUG, INFO, WARNING, ERROR (default: "INFO")
  • LOGGER_BACKUP_COUNT: Number of log files to retain (default: 30)
  • LOGGER_CONSOLE_OUTPUT: Enable console logging (default: True)

How to Modify

Edit src/config.py and change the values:

# Example: Increase cache time and reduce retries
CACHE_TTL_TIME: int = 300  # 5 minutes instead of 1
MAX_RETRIES: int = 2       # 2 retries instead of 3

# Example: Enable debug logging
LOG_LEVEL: str = "DEBUG"

Note: Restart the server after making configuration changes for them to take effect.

🔑 API Information

No API Keys Required!

The Bitcoin MCP Server uses free, public APIs that don't require authentication or API keys. This makes setup incredibly simple - just install and go!

Data Sources

The server aggregates data from multiple reliable sources:

Fair Use Policy

While these APIs are free and don't require keys, please use them responsibly:

  • Avoid excessive requests: Don't spam the APIs with rapid-fire queries
  • Rate limiting: The server implements reasonable delays between requests
  • Be respectful: These services are provided free of charge to the community
  • Cache when possible: Results are cached to minimize redundant requests

Note: If you plan to use this server at high volume or in a production environment, consider using API keys or self-hosting Bitcoin Core nodes for data access.

⚠️ Usage Considerations

Message Limits

Using MCP servers will consume more tokens from your AI assistant's message allowance because:

  • Each tool call requires additional context to be sent
  • Results from APIs add to the total token count
  • Complex queries may require multiple tool calls

Impact: You may reach your daily message limit faster when using Bitcoin MCP tools extensively.

Rate Limiting

While the APIs are free, rate limits apply. Intensive usage may result in temporary blocks. Please refer to the client website for specific API usage limits.

CORS

The current configuration allows requests from any origin, which is acceptable for local development but should be explicitly restricted before any production deployment.

Note also that combining allow_origins=["*"] with allow_credentials=True is technically invalid per the CORS spec — browsers will reject credentialed cross-origin requests when the origin is a wildcard. Consider either disabling credentials or explicitly listing allowed origins.

🤝 Contributing

We welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated ❤️.

How to Contribute

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test with MCP Inspector
  5. Commit your changes
  6. Push to your branch
  7. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📄 License

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

🔒 Security

For security concerns or vulnerability reports, please see our Security Policy.

This project was not vibe-coded.

bitcoin love

About

The MCP Server dedicated to Bitcoin ecosystem

Topics

ai bitcoin mcp blockchain trade ai-agents ai-tools mcp-server

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

6 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases 2

Release v1.1.0 - Python Compatibility Update Latest
Jan 31, 2026
+ 1 release

Contributors

Languages