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

- **Type:** MCP server
- **Install:** `agentstack add mcp-joaquinbejar-deribit-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [joaquinbejar](https://agentstack.voostack.com/s/joaquinbejar)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [joaquinbejar](https://github.com/joaquinbejar)
- **Source:** https://github.com/joaquinbejar/deribit-mcp

## Install

```sh
agentstack add mcp-joaquinbejar-deribit-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[](./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:

```bash
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):

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

**`docker run`**:

```bash
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`**:

```bash
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:

```bash
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)

```json
{
  "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)

```json
{
  "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`:

```bash
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](https://github.com/joaquinbejar)
- **Source:** [joaquinbejar/deribit-mcp](https://github.com/joaquinbejar/deribit-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-joaquinbejar-deribit-mcp
- Seller: https://agentstack.voostack.com/s/joaquinbejar
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.