Hyblock Capital MCP Server

An MCP server exposing the full Hyblock Capital API as tools for AI assistants (Claude, Gemini, etc.).

Transport: HTTP (MCP over stdio → upstream calls via HTTPS to Hyblock API)

---

Features

• ✅ 53 tools covering all Hyblock API endpoints
• ✅ OAuth2 token caching — automatically refreshes tokens before expiry
• ✅ Typed parameters with descriptions for every tool
• ✅ Clear error messages including HTTP status codes from the API

Tool Categories

Category	Tools
System	ping, catalog, data_availability
Orderflow	klines, buy_volume, sell_volume, volume_delta, volume_ratio, anchored_cvd, bot_tracker, slippage, transfer_of_contracts, participation_ratio, market_order_count, market_order_average_size, limit_order_count, limit_order_average_size, buy_sell_trade_count_ratio, limit_order_count_ratio, market_order_count_ratio, exchange_premium, pd_levels
Funding Rate	funding_rate
Longs & Shorts	top_trader_accounts, top_trader_positions, global_accounts, net_long_short, whale_retail_delta, trader_sentiment_gap
Orderbook	bid_ask, bid_ask_ratio, bid_ask_delta, combined_book, market_imbalance_index
Global Metrics	global_bid_ask_ratio, global_combined_book
Open Interest	open_interest, open_interest_delta
Options	bvol, dvol
Sentiment	margin_lending_ratio, fear_and_greed_index, user_bot_ratio
Liquidity	liquidation, liq_levels_count, liq_levels_size, liquidation_heatmap, avg_leverage_used
Profile Tool	indicator_profile, coin_profile

---

Prerequisites

1. A Hyblock Capital account with API access
2. Your client_id, client_secret, and x-api-key from the API Explorer
3. Node.js ≥ 18

---

Setup

git clone <repo-url>
cd mcp
npm install
npm run build

---

Configuration

Set these environment variables before running (locally or in Railway):

export HYBLOCK_CLIENT_ID="your_client_id"
export HYBLOCK_CLIENT_SECRET="your_client_secret"
export HYBLOCK_API_KEY="your_api_key"

Add the server to your MCP client configuration (e.g., claude_desktop_config.json).

Option 1: Local Deployment (Standard)

Use this if you are running the server on your own machine.

{
  "mcpServers": {
    "hyblock-local": {
      "command": "node",
      "args": ["mcp/dist/index.js"],
      "env": {
        "HYBLOCK_CLIENT_ID": "your_client_id",
        "HYBLOCK_CLIENT_SECRET": "your_client_secret",
        "HYBLOCK_API_KEY": "your_api_key"
      }
    }
  }
}

Option 2: Deployed Deployment (Railway / Cloud)

Use this if you have deployed the server to Railway. This uses the SSE (Server-Sent Events) over HTTP transport.

Setup in Railway

1. Connect your GitHub repository to Railway.
2. Add the following Environment Variables (all are required; the server will refuse to start if any are missing or empty):
   • HYBLOCK_CLIENT_ID
   • HYBLOCK_CLIENT_SECRET
   • HYBLOCK_API_KEY
3. Railway will use the Dockerfile to build and deploy. It will automatically assign a PORT.

How to "Enter" in MCP Clients

Once live, your server will have a base URL (e.g., https://hyblock-mcp-production.up.railway.app).

For most MCP clients (like Claude Desktop), you must point them to the /sse endpoint, not the bare root:

{
  "mcpServers": {
    "hyblock-remote": {
      "url": "https://your-railway-app.up.railway.app/sse"
    }
  }
}

Note: If your client doesn't support the url field yet, you can use a small node bridge or the local version.

If you see ❌ API Error (401) or ❌ API Error (403) from any Hyblock tools, first verify that:

• HYBLOCK_CLIENT_ID, HYBLOCK_CLIENT_SECRET, and HYBLOCK_API_KEY are correctly set in the server environment (Railway or local).
• Your MCP client configuration is using the /sse endpoint as shown above.

---

Authentication Flow

The server implements the OAuth2 Client Credentials flow automatically:

1. On first API call, it exchanges client_id:client_secret (Base64 encoded) for a Bearer token via POST /oauth2/token
2. The token is cached in memory until 60 seconds before expiry
3. Subsequent calls reuse the cached token — no manual refresh needed

---

Tools Categorization

The server exposes 53 tools across these areas:

• System: Health check, Catalog (use this to find valid coins/exchanges).
• Orderflow: 19 tools (CVD, Bot Tracker, Slippage, etc).
• Funding: Perpetual funding rates.
• Liquidity: Liquidation heatmaps and levels.
• Sentiment: Whale/Retail delta and market sentiment indexes.
• And more...

Common Parameters

Most tools accept these optional parameters:

Parameter	Type	Description
timeframe	string	1m, 5m, 15m, 1h, 4h, 1d
limit	number	Records to return (max 1000)
startTime	number	Start of range (Unix ms)
endTime	number	End of range (Unix ms)
sort	string	asc or desc

Tip: Call hyblock_catalog first to discover valid coin and exchange values.