# 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.

![Bitcoin](https://img.shields.io/badge/Bitcoin-F7931A?logo=bitcoin&logoColor=white)
![Bitcoin MCP](https://img.shields.io/badge/github-Bitcoin%20MCP-blue?logo=github)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)


---

## 📋 Table of Contents

- [What is MCP?](#-what-is-mcp)
- [Why Use Bitcoin MCP Server?](#-why-use-bitcoin-mcp-server)
- [Features](#-features)
- [Installation](#-installation)
- [API Information](#-api-information)
- [Use Cases](#-use-cases)
- [Available Tools](#-available-tools)
- [Configuration](#-configuration)
- [Usage Considerations](#-usage-considerations)
- [Roadmap](#-roadmap)
- [Contributing](#-contributing)
- [License](#-license)

---

## 🤖 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](https://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](https://github.com/user-attachments/assets/d10cf426-5c05-4ea4-950f-d766a1a9b2ed)

### For Developers & Analysts

![img](https://github.com/user-attachments/assets/3e6c905b-454a-4c44-8cd7-4c56292f8e75)

### For Researchers & Educators

![img](https://github.com/user-attachments/assets/bd48499c-a27b-47ee-98dc-3b0eccea865c)

### For Business Intelligence

![img](https://github.com/user-attachments/assets/87693e81-84a8-4f61-9d65-a6eecdb4432c)

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 :
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

- Windows :
```bash
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
Restart your command-line window after installing this.

2. **Clone the repository**:
```bash
git clone https://github.com/teamssUTXO/bitcoin_mcp.git
cd bitcoin_mcp
```

3. **Install dependencies**:
```bash
uv venv
uv pip install -e .
```

4. **Install to Claude Desktop**:
```bash
uv run mcp install src/main.py
```

Check [How to configure MCP Server](mcp_config/README.md)

### Option 2: Using Python/Pip

1. **Clone the repository**:
```bash
git clone https://github.com/teamssutxo/bitcoin_mcp.git
cd bitcoin_mcp
```

2. **Create a virtual environment** (recommended):
```bash
python -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate
```

3. **Install dependencies**:
```bash
pip install -r requirements.txt
```

4. **Run the server with Claude Desktop**:

Follow the Claude configuration guide: : [Config.README.md](mcp_config/README.md)

### Option 3: Using Docker

See [README.Docker.md](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:
```bash
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](mcp_config/README.md).

### 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:
```python
# 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:

- **[Blockchain.com](https://blockchain.com)**
- **[Mempool.space](https://mempool.space)**
- **[CoinGecko](https://coingecko.com)**
- **[Alternative](https://alternative.me/crypto/coins/)**

### 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](CONTRIBUTING.md) for detailed guidelines.

---

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

---

## 🔒 Security

For security concerns or vulnerability reports, please see our [Security Policy](SECURITY.md).

---

This project was not vibe-coded.

![bitcoin love](https://img.shields.io/badge/spread%20the%20bitcoin%20love%20<3-f00020)