CoinGlass MCP Server

MCP server for CoinGlass 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

pip install coinglass-mcp

Or with uv:

uv pip install coinglass-mcp

Configuration

export COINGLASS_API_KEY="your-api-key"
export COINGLASS_PLAN="standard"  # hobbyist | startup | standard | professional | enterprise

Get your API key at coinglass.com/pricing

Run

coinglass-mcp

---

Claude Desktop Integration

Add to your claude_desktop_config.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

# 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

# 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

# Current funding rates
coinglass_funding_current(action="rates")

# Find arbitrage opportunities
coinglass_funding_current(action="arbitrage")

Whale Tracking

# Recent whale alerts (Hyperliquid)
coinglass_whale_positions(action="alerts")

# Large BTC positions
coinglass_whale_positions(action="positions", symbol="BTC")

Market Sentiment

# Fear & Greed Index
coinglass_indicators(action="fear_greed")

# Bitcoin Rainbow Chart
coinglass_indicators(action="rainbow")

Tool Discovery

# 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

git clone https://github.com/forgequant/coinglass-mcp.git
cd coinglass-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

Testing

pytest -v

======================== 45 passed in 0.69s ========================

Run Locally

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

---

License

MIT

---

Links

• CoinGlass — Cryptocurrency derivatives analytics
• FastMCP — Fast, Pythonic MCP server framework
• MCP Protocol — Model Context Protocol specification