Deribit Mcp

[](./LICENSE) [](https://crates.io/crates/deribit-mcp) [](https://crates.io/crates/deribit-mcp) [](https://github.com/joaquinbejar/deribit-mcp/stargazers) [](https://github.com/joaquinbejar/deribit-mcp/issues) [](https://github.com/joaquinbejar/deribit-mcp/pulls) [](https://github.com/joaquinbejar/deribit-mcp/actions) [](https://codecov.io/gh/joaquinbejar/deribit-mcp) [](https://libraries.io/github/joaquinbejar/deribit-mcp) [](https://docs.rs/deribit-mcp) [](https://deepwiki.com/joaquinbejar/deribit-mcp)

deribit-mcp

Model Context Protocol (MCP) server for the Deribit cryptocurrency derivatives platform. Single binary crate that adapts the deribit-base, deribit-http, deribit-websocket, and (optional) deribit-fix stack onto MCP's tool / resource / prompt surface.

This is a thin adapter — every MCP tool is a translation step over an upstream call. Auth, rate limiting, reconnect, and wire codecs live in the sibling crates.

Quick start

The fastest path is Docker — clone the repo, drop credentials in .env, run compose. The binary also installs with cargo install.

1. Get credentials

Create a Deribit API key at (testnet) or (mainnet). Account → API → Add new key. You only need client_id and client_secret. Public Read tools work without credentials; Account / Trading tools require them.

2. Configure

Copy .env.example to .env at the repository root and fill in:

DERIBIT_NETWORK=testnet                # or `mainnet`
DERIBIT_CLIENT_ID=your_client_id
DERIBIT_CLIENT_SECRET=your_client_secret
# Optional — gates the HTTP endpoint with a static bearer:
DERIBIT_HTTP_BEARER_TOKEN=
RUST_LOG=info,deribit_mcp=debug

.env is git-ignored (mode 600 recommended). Credentials never appear on the command line — they live in the environment only.

3. Deploy

Docker compose (recommended):

docker compose -f Docker/docker-compose.yml up -d
curl -sf http://127.0.0.1:8723/healthz && echo "ok"

docker run:

docker build -f Docker/Dockerfile -t deribit-mcp:local .
docker run -d --name deribit-mcp \
  --restart unless-stopped \
  --env-file .env \
  -p 127.0.0.1:8723:8723 \
  deribit-mcp:local \
  --transport=http --listen=0.0.0.0:8723

cargo install:

cargo install --path . --locked
deribit-mcp --transport=stdio
# or
deribit-mcp --transport=http --listen=0.0.0.0:8723

The HTTP runtime image is distroless — no shell, no package manager, runs as nonroot. Health probe is GET /healthz (unauthenticated, returns 200 OK while the server accepts requests).

4. Enable trading (opt-in)

Trading tools (place_order, edit_order, cancel_order, cancel_all_by_*) are absent from tools/list unless you launch with --allow-trading AND credentials are configured. Add a notional cap to keep blast-radius bounded:

deribit-mcp --transport=http --listen=0.0.0.0:8723 \
  --allow-trading --max-order-usd=100

The cap classifies inverse vs linear instruments and falls back to the upstream mark price for market orders that don't carry a price.

Use from Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Option A — HTTP (uses the running container)

{
  "mcpServers": {
    "deribit": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8723/mcp"
      ]
    }
  }
}

If you set DERIBIT_HTTP_BEARER_TOKEN, append "--header", "Authorization: Bearer YOUR_TOKEN" to args.

Option B — stdio (no Docker)

{
  "mcpServers": {
    "deribit": {
      "command": "/Users/you/.cargo/bin/deribit-mcp",
      "args": ["--transport=stdio"],
      "env": {
        "DERIBIT_NETWORK": "testnet",
        "DERIBIT_CLIENT_ID": "...",
        "DERIBIT_CLIENT_SECRET": "..."
      }
    }
  }
}

Quit Claude Desktop completely (⌘Q on macOS — including the menubar icon) and relaunch. The slash menu should now show deribit:get_ticker, deribit:get_currencies, etc.

Sample prompts

Paste any of these into Claude Desktop after the deribit connector is active. Each one exercises a specific tool, resource, or curated prompt; together they cover the full MCP surface.

Public market data — Read tools (no credentials)

• get_server_time — "Using the deribit MCP server, give me

the current Deribit server time as a Unix-ms timestamp."

• get_status — "Using deribit, call get_status and tell me

if any currency is locked."

• get_currencies — "Using deribit, list all currencies with

their long names, fee precision, and minimum withdrawal fee."

• get_index_price — "Using deribit, fetch the BTC USD index

price (get_index_price, index_name=btc_usd)."

• get_ticker — "Using deribit, give me the BTC-PERPETUAL

ticker. Summarize in one line: mark, last, best bid, best ask, 24h volume."

• get_instrument — "Using deribit, call get_instrument for

BTC-PERPETUAL and tell me the contract size, tick size, and minimum trade amount."

• list_instruments — "Using deribit, list every active

option for ETH (list_instruments, currency=ETH, kind=option, expired=false). Group by expiration date."

• get_order_book — "Using deribit, fetch the BTC-PERPETUAL

order book at depth 10 and show me the best 5 levels each side."

• get_book_summary_by_currency — "Using deribit, get a book

summary for every BTC future (get_book_summary_by_currency, currency=BTC, kind=future). Sort by 24h volume descending."

• get_book_summary_by_instrument — "Using deribit, give me

the book summary for BTC-PERPETUAL only."

• get_last_trades — "Using deribit, fetch the last 50 trades

on BTC-PERPETUAL (get_last_trades, count=50). Tell me the buy/sell ratio."

• get_tradingview_chart_data — "Using deribit, pull 1-hour

candles for BTC-PERPETUAL covering the last 24 hours via get_tradingview_chart_data. Identify the hour with the widest range."

• get_funding_rate_history — "Using deribit, fetch

get_funding_rate_history for BTC-PERPETUAL covering the last 24h. Compute the mean."

• get_historical_volatility — "Using deribit, fetch

get_historical_volatility for BTC and ETH. Compare the most recent values."

Authenticated reads — Account tools (credentials

required)

• get_account_summary — "Using deribit, give me

get_account_summary for BTC with extended=true. Show equity, initial margin, maintenance margin, P&L, available balance."

• get_positions — "Using deribit, list my open BTC

positions. Flag any with margin utilization above 70%."

• get_subaccounts — "Using deribit, list my subaccounts

(get_subaccounts, with_portfolio=true)."

• get_transaction_log — "Using deribit,

get_transaction_log for BTC over the last 24 hours. Group by type."

• get_deposits — "Using deribit, show my last 10 BTC

deposits (get_deposits, currency=BTC, count=10)."

• get_withdrawals — "Using deribit, show my last 10 BTC

withdrawals."

• get_open_orders_by_currency — "Using deribit, list every

open BTC order. Mark anything older than 24 hours."

• get_open_orders_by_instrument — "Using deribit, list open

orders on BTC-PERPETUAL only."

• get_user_trades_by_currency — "Using deribit, fetch the

last 50 BTC user trades (get_user_trades_by_currency, currency=BTC, count=50). Compute net realized P&L."

• get_user_trades_by_instrument — "Using deribit, fetch user

trades for BTC-PERPETUAL over the last 24 hours."

Order entry — Trading tools (--allow-trading)

Always test on testnet first. Use a small --max-order-usd cap.

• place_order (limit buy) — "Using deribit, place a buy

limit order for 10 USD of BTC-PERPETUAL at half the current mark price, post-only, label prompt-test."

• place_order (stop-limit) — "Using deribit, place a

stop-limit sell on BTC-PERPETUAL: amount 10, price 90000, trigger_price 91000, trigger=mark_price."

• edit_order — "Using deribit, edit order

`` to amount 20 and price 51000."

• cancel_order — "Using deribit, cancel order

``."

• cancel_all_by_currency — "Using deribit, cancel every

open BTC order (cancel_all_by_currency, currency=BTC). Tell me how many were cancelled."

• cancel_all_by_instrument — "Using deribit, cancel every

open BTC-PERPETUAL order."

Resources

• deribit://currencies (static) — "Using deribit, read the

resource deribit://currencies and list each currency with its withdrawal_fee."

• deribit://instruments/{currency} (template) — "Using

deribit, read deribit://instruments/BTC and tell me how many futures are listed."

• deribit://book/{instrument} (live) — "Using deribit, read

deribit://book/BTC-PERPETUAL and show the top 5 bids and asks."

• deribit://ticker/{instrument} (live) — "Using deribit,

read deribit://ticker/BTC-PERPETUAL."

• deribit://trades/{instrument} (live) — "Using deribit,

read deribit://trades/BTC-PERPETUAL and tell me the trade-size distribution."

Curated prompts

MCP prompts are exposed as slash-commands in Claude Desktop — the user (not Claude) types them. Once the slash-command is expanded the curated message pair lands in the conversation and Claude follows the instructions, calling the tools the prompt names. The naming convention is /mcp____ (double underscores).

• daily_options_summary — type

/mcp__deribit__daily_options_summary and supply currency=BTC, horizon_days=7. Drives Claude through list_instruments, get_book_summary_by_currency, and get_historical_volatility, then produces a four-section summary (ATM IV vs RV headline, top calls + puts by OI, skew commentary, caveats).

• funding_snapshot — type

/mcp__deribit__funding_snapshot and supply currency=BTC, lookback_hours=24. Drives Claude through list_instruments (perpetual filter) and get_funding_rate_history, then produces a table (latest, mean / median / p10 / p90, sign breakdown, outliers, caveats).

• position_review — type

/mcp__deribit__position_review and supply currency=BTC, include_history=true. Drives Claude through get_account_summary, get_positions, get_open_orders_by_currency, and (when include_history=true) get_user_trades_by_currency, then produces a report (headline, positions, open orders, flags, recent trades, caveats). When credentials are missing the prompt returns a structured warning instead.

If you want Claude to perform an equivalent workflow without invoking the slash-command, ask directly — for example: "Using deribit, summarize BTC options expiring in the next 7 days. Run list_instruments (kind=option), filter by expiration_timestamp within 7 days, then get_book_summary_by_currency and get_historical_volatility. Produce: ATM IV vs RV headline; top 3 calls and puts by open interest; skew commentary; caveats." That bypasses the curated prompt but reaches the same result.

Negative paths (gating verification)

• "Using deribit, try place_order with no credentials

configured. What does the registry say?" (Should be absent from tools/list.)

• "Using deribit, call get_account_summary for currency

XYZ." (Should return a structured Validation error.)

Capability surface (v1.0.0)

| Class | Count | Examples | |---|---:|---| | Read tools (no auth) | 14 | get_ticker, get_currencies, get_order_book, get_book_summary_by_currency, get_funding_rate_history, get_historical_volatility, get_last_trades, get_tradingview_chart_data, get_index_price, get_server_time, get_status | | Account tools (creds) | 10 | get_account_summary, get_positions, get_subaccounts, get_open_orders_by_currency, get_user_trades_by_currency, get_transaction_log, get_deposits, get_withdrawals | | Trading tools (--allow-trading) | 5 | place_order, edit_order, cancel_order, cancel_all_by_currency, cancel_all_by_instrument | | Resources | 1 + 4 templates | deribit://currencies, deribit://instruments/{currency}, deribit://book/{instrument}, deribit://ticker/{instrument}, deribit://trades/{instrument} | | Prompts | 3 | daily_options_summary, funding_snapshot, position_review |

The MCP wire shape is locked under SemVer from 1.0.0 — adding / renaming / removing tool fields, resource URIs, error variants, or prompt arguments requires a 2.0 major bump (see CHANGELOG.md).

Configuration reference

| Setting | CLI | Env var | Default | |---|---|---|---| | Network | --testnet / --mainnet | DERIBIT_NETWORK=testnet\|mainnet or DERIBIT_ENDPOINT= | testnet | | Credentials | — | DERIBIT_CLIENT_ID / DERIBIT_CLIENT_SECRET | none | | Trading opt-in | --allow-trading | DERIBIT_ALLOW_TRADING=1 | off | | Notional cap | --max-order-usd=N | DERIBIT_MAX_ORDER_USD=N | unlimited | | MCP transport | --transport=stdio\|http | DERIBIT_MCP_TRANSPORT | stdio | | HTTP listen | --listen=ADDR:PORT | DERIBIT_HTTP_LISTEN | 127.0.0.1:8723 | | HTTP bearer | — | DERIBIT_HTTP_BEARER_TOKEN | none (anonymous) | | Order transport | --order-transport=http\|fix | DERIBIT_ORDER_TRANSPORT | http | | Log filter | — | RUST_LOG | info | | Log format | --log-format=text\|json | DERIBIT_LOG_FORMAT | text on stdio, json on http |

CLI flags win over env vars; env vars win over .env; .env wins over built-in defaults.

Observability

Each MCP request emits two structured events on stderr (stdio) / stdout (http) — entry and outcome — with target deribit_mcp::request and elapsed_ms:

docker logs -f deribit-mcp 2>&1 | grep deribit_mcp::request

INFO deribit_mcp::request tools/call tool="get_ticker"
INFO deribit_mcp::request tools/call ok tool="get_ticker" elapsed_ms=75
WARN deribit_mcp::request tools/call error tool="missing" elapsed_ms=0 error="..."

Secrets (client_secret, access_token, refresh_token, http_bearer_token) are redacted before they reach any tracing sink.

Troubleshooting

| Symptom | Likely cause | Fix | |---|---|---| | tools/call returns -32601 method not found | Old image without the ServerHandler::call_tool override | Rebuild: docker compose -f Docker/docker-compose.yml build --no-cache | | Every /mcp request returns 401 | DERIBIT_HTTP_BEARER_TOKEN set in env (even empty = lines) | Remove the line from .env or pass Authorization: Bearer ... from the client | | Upstream { error decoding response body } | Custom endpoint URL missing /api/v2 suffix | Use DERIBIT_NETWORK=testnet\|mainnet instead of DERIBIT_ENDPOINT; the canonical paths are auto-applied | | Account / Trading tools missing from tools/list | Credentials not loaded | Verify docker inspect shows DERIBIT_CLIENT_ID and DERIBIT_CLIENT_SECRET | | Trading tools missing despite credentials | --allow-trading not set | Add it to the command: block in compose | | Claude Desktop says "connector not responding" | Cached old session in mcp-remote | Quit Claude Desktop with ⌘Q (also the menubar icon), relaunch | | mcp-remote rejects with "Invalid input in structuredContent" | Old server before scalar-wrap fix | Pull / rebuild — the adapter wraps non-object payloads in {"value": ...} since v1.0 |

Build problems? cargo install requires cmake, perl, pkg-config, and libssl-dev (or openssl-devel) for the FIX dependency chain. Docker handles this automatically.

Crate layout

• [config] — CLI argument and .env resolution.
• [context] — AdapterContext shared across handlers.
• [error] — AdapterError and From impls for upstream errors.
• [server] — rmcp Server scaffold.
• [observability] — tracing setup and secret redaction.
• [tools] — Read / Account / Trading tool families.
• [resources] — static and live resource families.
• [prompts] — cura

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: joaquinbejar
• Source: joaquinbejar/deribit-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.