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

coinglass-mcp