# CoinGlass MCP Server
[](https://www.python.org/downloads/)
[](https://github.com/jlowin/fastmcp)
[](https://opensource.org/licenses/MIT)
[](https://github.com/astral-sh/ruff)
[](#testing)
> MCP server for [CoinGlass](https://www.coinglass.com) cryptocurrency derivatives analytics. Provides AI agents access to **80+ API endpoints** through **22 unified tools**.
---
## Features
- **22 MCP Tools** — Unified interface to 80+ CoinGlass API endpoints
- **Plan-Aware Gating** — Automatic feature restrictions based on subscription tier
- **Response Caching** — Built-in caching via FastMCP middleware (60s TTL)
- **Retry Logic** — Automatic retries for transient failures (5xx, timeouts)
- **Type-Safe** — Full type hints with Literal-typed actions for LLM clarity
- **Async-First** — Built on httpx + FastMCP for high performance
---
## Quick Start
### Installation
```bash
pip install coinglass-mcp
```
Or with [uv](https://github.com/astral-sh/uv):
```bash
uv pip install coinglass-mcp
```
### Configuration
```bash
export COINGLASS_API_KEY="your-api-key"
export COINGLASS_PLAN="standard" # hobbyist | startup | standard | professional | enterprise
```
> Get your API key at [coinglass.com/pricing](https://www.coinglass.com/pricing)
### Run
```bash
coinglass-mcp
```
---
## Claude Desktop Integration
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"coinglass": {
"command": "coinglass-mcp",
"env": {
"COINGLASS_API_KEY": "your-api-key",
"COINGLASS_PLAN": "standard"
}
}
}
}
```
---
## Available Tools
| Category | Tool | Description |
|----------|------|-------------|
| **Market** | `coinglass_market_info` | Supported coins, pairs, exchanges |
| | `coinglass_market_data` | Real-time market summaries |
| | `coinglass_price_history` | OHLC price candles |
| **Open Interest** | `coinglass_oi_history` | OI OHLC (pair/aggregated/stablecoin/coin-margin) |
| | `coinglass_oi_distribution` | OI breakdown by exchange |
| **Funding** | `coinglass_funding_history` | Funding rate OHLC |
| | `coinglass_funding_current` | Current rates, accumulated, arbitrage |
| **Long/Short** | `coinglass_long_short` | Global ratio, top accounts, top positions |
| **Liquidation** | `coinglass_liq_history` | Liquidation OHLC history |
| | `coinglass_liq_orders` | Real-time liquidation stream ⚡ |
| | `coinglass_liq_heatmap` | Liquidation heatmaps 🔥 |
| **Order Book** | `coinglass_ob_history` | Bid/ask depth history |
| | `coinglass_ob_large_orders` | Whale walls detection |
| **Whale** | `coinglass_whale_positions` | Hyperliquid whale positions ⚡ |
| | `coinglass_whale_index` | Whale activity index |
| **Taker** | `coinglass_taker` | Taker buy/sell volume and ratio |
| **Spot** | `coinglass_spot` | Spot market data and prices |
| **Options** | `coinglass_options` | Max pain, OI, volume (BTC/ETH) |
| **On-Chain** | `coinglass_onchain` | Exchange balances, flows, transfers |
| **ETF** | `coinglass_etf` | Bitcoin/Ethereum ETF flows |
| | `coinglass_grayscale` | Grayscale holdings and premium |
| **Indicators** | `coinglass_indicators` | RSI, Fear & Greed, Rainbow, Pi Cycle, etc. |
| **Meta** | `coinglass_search` | Discover tools by keyword |
| | `coinglass_config` | View exchanges, intervals, features |
> ⚡ Requires Startup+ plan | 🔥 Requires Professional+ plan
---
## Plan Features
| Feature | Hobbyist | Startup | Standard | Professional |
|---------|:--------:|:-------:|:--------:|:------------:|
| Basic intervals (h4, h8, d1) | ✅ | ✅ | ✅ | ✅ |
| Extended intervals (m1-h1) | ❌ | ✅ | ✅ | ✅ |
| Whale alerts & positions | ❌ | ✅ | ✅ | ✅ |
| Liquidation orders stream | ❌ | ❌ | ✅ | ✅ |
| Liquidation heatmaps | ❌ | ❌ | ❌ | ✅ |
---
## Usage Examples
### Market Overview
```python
# Get all coins summary
coinglass_market_data(action="coins_summary")
# Get BTC metrics only
coinglass_market_data(action="coins_summary", symbol="BTC")
```
### Open Interest Analysis
```python
# BTC OI across all exchanges
coinglass_oi_history(action="aggregated", symbol="BTC")
# OI distribution by exchange
coinglass_oi_distribution(action="by_exchange", symbol="BTC")
```
### Funding Rate Arbitrage
```python
# Current funding rates
coinglass_funding_current(action="rates")
# Find arbitrage opportunities
coinglass_funding_current(action="arbitrage")
```
### Whale Tracking
```python
# Recent whale alerts (Hyperliquid)
coinglass_whale_positions(action="alerts")
# Large BTC positions
coinglass_whale_positions(action="positions", symbol="BTC")
```
### Market Sentiment
```python
# Fear & Greed Index
coinglass_indicators(action="fear_greed")
# Bitcoin Rainbow Chart
coinglass_indicators(action="rainbow")
```
### Tool Discovery
```python
# Search for liquidation-related tools
coinglass_search(query="liquidation")
# Check available features for your plan
coinglass_config(action="plan_features")
```
---
## Architecture
```
coinglass-mcp/
├── src/coinglass_mcp/
│ ├── server.py # FastMCP server + 22 tools
│ ├── client.py # HTTP client with retry logic
│ └── config.py # Plan tiers, intervals, features
├── tests/
│ ├── test_client.py
│ └── test_tools.py
└── pyproject.toml
```
**Design Principles:**
- **3-file architecture** — Optimized for AI agent comprehension
- **Domain facade pattern** — 22 tools → 80+ endpoints
- **Literal-typed actions** — Helps LLMs select correct operations
- **Lifespan pattern** — Shared httpx.AsyncClient for efficiency
---
## Development
### Setup
```bash
git clone https://github.com/forgequant/coinglass-mcp.git
cd coinglass-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
```
### Testing
```bash
pytest -v
```
```
======================== 45 passed in 0.69s ========================
```
### Run Locally
```bash
export COINGLASS_API_KEY="your-key"
python -m coinglass_mcp.server
```
---
## FastMCP Cloud Deployment
**Entry point:** `coinglass_mcp.server:mcp`
**Environment variables:**
- `COINGLASS_API_KEY` — Your CoinGlass API key
- `COINGLASS_PLAN` — Subscription tier (default: `standard`)
---
## API Reference
Full CoinGlass API documentation: [open-api.coinglass.com](https://open-api.coinglass.com/)
---
## License
MIT
---
## Links
- [CoinGlass](https://www.coinglass.com) — Cryptocurrency derivatives analytics
- [FastMCP](https://github.com/jlowin/fastmcp) — Fast, Pythonic MCP server framework
- [MCP Protocol](https://modelcontextprotocol.io) — Model Context Protocol specification
