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

1. 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.