# Crypto Price MCP Server 💰📊

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](LICENSE)
[![Stars](https://img.shields.io/github/stars/ceeyang-ai/crypto-price-mcp-server?style=flat-square)](https://github.com/ceeyang-ai/crypto-price-mcp-server)
[![MCP](https://img.shields.io/badge/MCP-Server-5e81ac?style=flat-square)](https://modelcontextprotocol.io)
[![GitHub](https://img.shields.io/badge/GitHub-ceeyang--ai/crypto--price--mcp--server-black?logo=github)](https://github.com/ceeyang-ai/crypto-price-mcp-server)

A **Model Context Protocol (MCP)** server for real-time cryptocurrency price data — prices, market data, trending coins, historical charts, and currency conversion. Powered by the free [CoinGecko API](https://www.coingecko.com/en/api) — **no API key required**.

> Built for AI agents. Works with **Hermes Agent**, **Claude Code**, **Cursor**, **Windsurf**, and any MCP-compatible client.

## ✨ Features (9 Tools)

### 💵 Price & Conversion (2 Tools)
| Tool | Description |
|------|-------------|
| `get_price` | Current price of any crypto in any currency (USD, EUR, JPY, BTC, etc.) |
| `convert_currency` | Convert an amount of one crypto to another currency in real time |

### 📊 Market Data (2 Tools)
| Tool | Description |
|------|-------------|
| `get_market_data` | Full market snapshot: rank, market cap, supply, ATH, 24h/7d/30d change |
| `get_global_stats` | Overall crypto market: total cap ($2.25T+), 24h volume, BTC/ETH dominance |

### 🔥 Discovery (3 Tools)
| Tool | Description |
|------|-------------|
| `get_trending` | Top 15 trending coins on CoinGecko right now |
| `get_top_gainers` | Top gainers/losers in the last 24 hours |
| `search_coins` | Search coins by name or symbol |

### 📈 Historical (1 Tool)
| Tool | Description |
|------|-------------|
| `get_historical_prices` | Historical daily OHLC prices (1d, 7d, 30d, 90d, 365d, max) |

### ℹ️ Info (1 Tool)
| Tool | Description |
|------|-------------|
| `get_coin_info` | Detailed coin info: description, links, categories, genesis date |

## 🚀 Quick Start

### Install

```bash
# From GitHub
pip install git+https://github.com/ceeyang-ai/crypto-price-mcp-server.git
```

### Run

```bash
# Start as MCP server (stdio mode)
crypto-price-mcp-server
```

## 🔌 Usage with AI Agents

### Hermes Agent

Add to `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  crypto-price:
    command: "crypto-price-mcp-server"
```

Restart → use `mcp_crypto_price_get_price`, `mcp_crypto_price_get_trending`, etc.

### Claude Code / Cursor / Any MCP Client

Add to your MCP config:

```json
{
  "mcpServers": {
    "crypto-price": {
      "command": "crypto-price-mcp-server"
    }
  }
}
```

## 📖 Examples

### Check Bitcoin Price

```
get_price(coin_id="bitcoin", vs_currency="usd")
```

Returns:
```
**BITCOIN** (USD)
• Price: 62,807
```

### What's Trending?

```
get_trending()
```

Returns top 15 trending coins with rank, BTC price, and score.

### Full Market Analysis

```
get_market_data(coin_id="solana", vs_currency="usd")
```

Returns rank, price, market cap, volume, supply, ATH, 24h/7d/30d change percentages.

### Historical Data

```
get_historical_prices(coin_id="bitcoin", vs_currency="usd", days=7)
```

Returns open, close, high, low, change percentage, and recent data points.

### Convert Crypto

```
convert_currency(coin_id="bitcoin", amount=0.5, vs_currency="usd")
```

Returns:
```
💱 **0.5 BITCOIN** = **31,417.50 USD**
   Rate: 1 BITCOIN = 62,835 USD
```

## 🛠 Requirements

- Python 3.10+
- mcp ≥ 1.0
- httpx ≥ 0.27
- Internet access (CoinGecko API)
- **No API key required** (uses free public CoinGecko API)

## 🌐 API Dependencies

This server uses the [CoinGecko free API](https://www.coingecko.com/en/api):

- **Rate limit**: ~30 calls/minute (free tier)
- **No registration needed** — works out of the box
- **No API key required** for public endpoints

If you need higher rate limits, consider using a CoinGecko API key with the `x_cg_demo_api_key` header (modify the `_request` function in `__init__.py`).

## 📦 Project Structure

```
crypto-price-mcp-server/
├── src/crypto_price_mcp_server/
│   └── __init__.py        # All 9 tools + CoinGecko API client
├── pyproject.toml          # Build config (setuptools)
├── README.md
└── LICENSE (MIT)
```

## 👨‍💻 Development

```bash
git clone https://github.com/ceeyang-ai/crypto-price-mcp-server.git
cd crypto-price-mcp-server
pip install -e .
python -c "from crypto_price_mcp_server import get_price; print(get_price('bitcoin'))"
```

### Running Tests

```bash
python tests/test_server.py
```

Tests hit the real CoinGecko API — be mindful of the 30 calls/min rate limit.

## 📄 License

MIT — free for personal and commercial use.