Crate 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 https://test.deribit.com (testnet) or https://www.deribit.com (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 <order_id> to amount 20 and price 51000.”
• cancel_order — “Using deribit, cancel order <order_id>.”
• 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__<server>__<prompt> (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=<url>	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 <id> 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 — curated MCP prompts (registry + handlers).
• prelude — curated re-exports for downstream consumers.

Re-exports

pub use crate::context::AdapterContext;

pub use crate::context::AuthState;

pub use crate::error::AdapterError;

pub use crate::error::AuthFailureReason;

pub use crate::error::UpstreamErrorKind;

pub use crate::prompts::PromptEntry;

pub use crate::prompts::PromptHandlerFn;

pub use crate::prompts::PromptRegistry;

pub use crate::resources::ResourceContent;

pub use crate::resources::ResourceList;

pub use crate::resources::ResourceRegistry;

pub use crate::resources::ResourceUri;

pub use crate::resources::parse_resource_uri;

pub use crate::server::DeribitMcpServer;

pub use crate::server::MCP_PROTOCOL_VERSION;

pub use crate::tools::ToolClass;

pub use crate::tools::ToolEntry;

pub use crate::tools::ToolRegistry;

Modules

config

Configuration surface — CLI + env + .env loader.

context

Shared adapter context — the single value every handler holds.

error

Adapter error type that crosses the MCP boundary.

http_transport

HTTP / Streamable-HTTP transport for the adapter.

observability

Tracing setup and secret redaction.

prelude

Curated re-exports for the most-used items in the adapter.

prompts

Prompt registry, descriptor list, and dispatch.

resources

Resource registry, deribit:// URI parsing, and read dispatch.

server

rmcp::ServerHandler scaffold for the Deribit adapter.

tools

Tool registry, effect-class gating, and dispatch.