Coinglass

This project implements a Model Context Protocol (MCP) server for the CoinGlass API (v4). It lets MCP-compatible clients (AI assistants, IDE extensions, or custom apps) access futures market analytics such as Open Interest, Liquidations, Long/Short Ratio, and Funding Rates.

Features (MCP Tools)

The server exposes the following tools that MCP clients can call:

• COINGLASS_OPEN_INTEREST: Open interest exchange list for a symbol; optional history

  • Parameters: symbol (string), exchange? (string), includeHistory? (boolean), period? ("1h" | "4h" | "12h" | "24h")

• COINGLASS_LIQUIDATIONS_PAIR: Historical pair liquidations (v4 /api/futures/liquidation/history)

  • Parameters: exchange (string), symbol (string), interval? ("1m"|"3m"|"5m"|"15m"|"30m"|"1h"|"4h"|"6h"|"8h"|"12h"|"1d"|"1w"), limit?, start_time?, end_time?, prettyFormat? (default: true)

• COINGLASS_LIQUIDATIONS_COIN: Aggregated coin liquidations (v4 /api/futures/liquidation/aggregated-history)

  • Parameters: exchange_list (string), symbol (string), interval? (same as above), limit?, start_time?, end_time?, prettyFormat? (default: true)

• COINGLASS_LONG_SHORT_RATIO: Global account long/short ratio snapshot

  • Parameters: symbol (string), exchange? (string), period? ("1h" | "4h" | "12h" | "24h"), prettyFormat? (boolean, default: true)

• COINGLASS_FUNDING_RATE: Current funding rate across exchanges

  • Parameters: symbol (string), exchange? (string), prettyFormat? (boolean, default: true)

• COINGLASS_HYPERLIQUID_WHALE_ALERT: Real-time Hyperliquid whale alerts (>$1M)

• Parameters: prettyFormat? (boolean, default: true)

• COINGLASS_HYPERLIQUID_WHALE_POSITION: Real-time Hyperliquid whale positions (>$1M)

• Parameters: prettyFormat? (boolean, default: true)

Tool call responses always return a success code even in case of api errors. In case of error tool response includes the raw api response.

Prerequisites

• Node.js v20+ (CI uses Node 22)
• pnpm (https://pnpm.io/installation)

Installation

There are a few ways to run mcp-coinglass:

1. Using pnpm dlx (recommended for most MCP client setups)

Run the published package directly without a global install. See the MCP client config example below.

2. Global installation from npm (via pnpm)

pnpm add -g mcp-coinglass

3. Building from source (development)

pnpm install
pnpm run build
pnpm run start

4. For testing and development purposes use mcp inspector

# in the project root run,
pnpm run build
npx @modelcontextprotocol/inspector node dist/index.js

Configuration (Environment Variables)

This server requires a CoinGlass API key. All CoinGlass v4 endpoints require the CG-API-KEY header. Generate your API key from your account dashboard and supply it via environment variables. References:

• Authentication docs: https://docs.coinglass.com/reference/authentication
• Account/API key dashboard: https://www.coinglass.com/account

Create a .env file (or configure env in your MCP client) with:

COINGLASS_API_KEY=your_api_key_here

An .env.sample file is included as a reference; copy it to .env and fill in your key.

NOTE: All the available tools require an upgraded coinglass api plan to work

Running the Server with an MCP Client

MCP clients (assistants, IDE extensions) run this server as a background process. Configure your client with a server entry similar to the following.

Using pnpm dlx:

{
  "mcpServers": {
    "coinglass-mcp-server": {
      "command": "pnpm",
      "args": ["dlx", "mcp-coinglass"],
      "env": {
        "COINGLASS_API_KEY": "your_api_key_here"
      }
    }
  }
}

If globally installed (pnpm add -g mcp-coinglass):

{
  "mcpServers": {
    "coinglass-mcp-server": {
      "command": "mcp-coinglass",
      "args": [],
      "env": {
        "COINGLASS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Example Tool Invocations

MCP clients pass JSON parameters to tools. Examples:

{ "tool": "COINGLASS_OPEN_INTEREST", "params": { "symbol": "BTC", "includeHistory": true, "period": "24h" } }

{ "tool": "COINGLASS_LIQUIDATIONS", "params": { "symbol": "BTCUSDT", "timeframe": "4h" } }

{ "tool": "COINGLASS_LIQUIDATIONS_PAIR", "params": { "exchange": "Binance", "symbol": "BTCUSDT", "interval": "4h" } }

{ "tool": "COINGLASS_LIQUIDATIONS_COIN", "params": { "exchange_list": "Binance,OKX,Bybit", "symbol": "BTC", "interval": "1d" } }

{ "tool": "COINGLASS_LONG_SHORT_RATIO", "params": { "symbol": "ETH", "period": "1h" } }

{ "tool": "COINGLASS_FUNDING_RATE", "params": { "symbol": "SOL" } }

{ "tool": "COINGLASS_HYPERLIQUID_WHALE_ALERT", "params": {} }

{ "tool": "COINGLASS_HYPERLIQUID_WHALE_POSITION", "params": {} }

Default Human-Readable Output Examples (prettyFormat=true)

These are the default formatted outputs. Set prettyFormat to false to receive raw API-shaped responses.

Funding Rate

Funding Rate for BTCUSDT:
Average: 0.0100% | Next Funding: 2024-08-06T08:00:00.000Z
Exchanges: 12

{
  "averageRate": 0.0001,
  "nextFundingTime": 1722960000000,
  "exchanges": [
    { "exchange": "Binance", "rate": -0.0000335, "predictedRate": -0.00002, "nextFundingTime": 1722960000000 }
    // ...
  ]
}

Open Interest

Open Interest for BTCUSDT:
Total OI (All): $123456789
24h Change: 2.34%

{
  "exchangeList": [ /* ... */ ],
  "history": { /* optional when includeHistory=true */ }
}

Liquidations (Pair)

Liquidations (Pair) for BTCUSDT [48 points]:
Latest: Long $1.23M | Short $2.34M
Totals: Long $56.78M | Short $67.89M

{
  "latest": { /* latest data point */ },
  "totals": { "long": 56780000, "short": 67890000 },
  "points": [ /* ... */ ]
}

Liquidations (Coin Aggregated)

Liquidations (Coin Aggregated) for BTC [48 points]:
Latest: Long $1.23M | Short $2.34M
Totals: Long $56.78M | Short $67.89M

{
  "latest": { /* latest data point */ },
  "totals": { "long": 56780000, "short": 67890000 },
  "points": [ /* ... */ ]
}

Global Long/Short Account Ratio

Long/Short Ratio for BTCUSDT:
Long: 73.24% | Short: 26.76% | Ratio: 2.74

{
  "latest": { /* latest data point */ },
  "points": [ /* ... */ ]
}

Hyperliquid Whale Alert

Hyperliquid Whale Alerts: 8 events
Top 5 by position value:

{
  "top": [
    { "user": "0xabc...", "symbol": "BTC", "positionValueUsd": 2936421.48, "positionAction": 2, "createTime": 1745219477000 }
    // ...
  ],
  "events": [ /* ... */ ]
}

Hyperliquid Whale Position

Hyperliquid Whale Positions: 6 positions (top 5 by value)

{
  "top": [
    { "user": "0xdef...", "symbol": "ETH", "positionSize": -44727.13, "positionValueUsd": 73589542.55, "leverage": 25, "unrealizedPnl": 27033236.42, "marginMode": "cross", "updateTime": 1745219966000 }
    // ...
  ],
  "positions": [ /* ... */ ]
}

Scripts

• pnpm run build: Compile TypeScript to dist/ and make output executable
• pnpm run start: Run the built server over stdio (for MCP)
• pnpm run lint: Lint via Biome
• pnpm run format: Format via Biome

Endpoint References (v4)

This server calls these REST endpoints:

• Open Interest Exchange List: GET /api/futures/open-interest/exchange-list
• Open Interest History (OHLC): GET /api/futures/open-interest/history
• Liquidations History: GET /api/futures/liquidation/history
• Global Long/Short Account Ratio History: GET /api/futures/global-long-short-account-ratio/history
• Funding Rate Exchange List: GET /api/futures/funding-rate/exchange-list

Refer to the official docs for authentication and rate limits:

• https://docs.coinglass.com/reference/authentication