deribit-mcp

Connect Deribit to your AI assistant. Works with any MCP client such as Claude Code and Codex. One command to connect, letting your assistant check market data, view accounts, and manage orders.

claude mcp add deribit -- npx -y deribit-mcp

Once installed, you can ask: "What does BTC's options chain look like right now?", "Show me the implied volatility of call options expiring in March", "How much available margin do I have left in my account?"

Two safety defaults: it connects to the testnet by default and has trading disabled by default. To place real orders, you must explicitly enable both.

Installation

Claude Code

For market data only, no configuration needed:

claude mcp add deribit -- npx -y deribit-mcp

To view accounts and orders, add API credentials and switch to mainnet:

claude mcp add deribit \
  --env DERIBIT_ENV=prod \
  --env DERIBIT_CLIENT_ID=你的_client_id \
  --env DERIBIT_CLIENT_SECRET=你的_client_secret \
  -- npx -y deribit-mcp

Codex

Edit ~/.codex/config.toml (or .codex/config.toml in your project):

[mcp_servers.deribit]
command = "npx"
args = ["-y", "deribit-mcp"]

[mcp_servers.deribit.env]
DERIBIT_ENV = "prod"
DERIBIT_CLIENT_ID = "你的_client_id"
DERIBIT_CLIENT_SECRET = "你的_client_secret"

Other MCP clients

Any client that supports stdio can use it. The command is npx -y deribit-mcp, and configuration is passed via environment variables.

Running from source (optional)

If you want to pin a specific version or have modified the code yourself, you can point directly at the source without having to remember to rebuild after every change:

git clone https://github.com/freeeverett/deribit-mcp.git
cd deribit-mcp && npm install

[mcp_servers.deribit]
command = "npx"
args = ["tsx", "/绝对路径/deribit-mcp/src/index.ts"]

The trade-off is roughly double the startup time (about 160ms vs 77ms), and you need dependencies installed locally. For everyday use, npx -y deribit-mcp is still recommended.

Getting API credentials

Create a key in Deribit Account Settings → API.

It's recommended to grant the least privilege: if you only want the assistant to analyze for you, trade:read is enough — even if you accidentally enable the trading switch, it won't be able to place orders.

Related MCP server: Crypto Options Desk MCP

Configuration

The testnet is separate: accounts and API keys on test.deribit.com are completely incompatible with the mainnet. You need to register separately at test.deribit.com. The testnet offers free test coins, so it's a good place to run through the flow before switching to mainnet.

Full testnet integration tests

Create a git-ignored .env.test in the project root, containing only testnet API credentials:

DERIBIT_CLIENT_ID=你的测试网_client_id
DERIBIT_CLIENT_SECRET=你的测试网_client_secret

Then run:

npm run test:all

This entry point natively reads .env.test and forces a testnet connection (it will not use mainnet or custom endpoint settings from the file). It runs all 39 tools through a real stdio MCP client and requires the key to have trade:read_write: it creates, modifies, and cancels limit orders with a unique test tag, briefly opens and closes positions with market orders, and creates a test portfolio. When the script exits, it cancels orders by that tag as a fallback; if cleanup fails, the command exits with a failure. The existing npm run smoke remains a fast public-interface regression that requires no credentials.

About trading features

Order-related tools are disabled by default — unless you set DERIBIT_ENABLE_TRADING=true, your assistant won't even see these tools, so there's no risk of accidental use.

Once enabled, you can: place orders, modify orders, cancel orders, close positions, and create portfolio contracts.

Please be aware:

• These actions will produce real fills on your real account — the money is real

• It's recommended to get familiar with the flow on the testnet before considering mainnet

• When mainnet + trading are enabled, the service prints an explicit warning at startup, and the assistant also receives an instruction that it must confirm with the user before executing

• But the final gate is you: whenever an order request appears, read it carefully before clicking approve

If you only want the assistant to analyze and not touch orders, don't enable this switch — market data and account queries are completely unaffected.

What it can do

39 tools in total.

Market data (18, no credentials needed)

Instrument and currency lists, contract specs, expiration dates, options chains (open interest / implied volatility / bid-ask prices), real-time quotes and order book depth, option Greeks, historical candlesticks, mark price history, index spot and history, historical realized volatility, DVOL volatility index, perpetual funding rates, all-market trades, exchange volume, interest-bearing token APR, delivery prices, settlement and liquidation records, portfolio contracts, platform status, and exchange announcements.

Account and orders (16, credentials required)

Account equity and margin, all-currency overview and account locks, position details, sub-account list, portfolio margin simulation, fund flows, settlement and delivery records, deposit/withdrawal/transfer history, current open orders, order status, historical orders, trigger order history, trade details, fills for a single order, and order margin estimation.

Trading (5, credentials required and explicitly enabled)

Place orders (limit / market / stop loss / take profit / trailing stop / iceberg / advanced option pricing), modify orders, cancel orders, close positions, and create multi-leg portfolio contracts.

See docs/API-COVERAGE.md for the full mapping of tools to API endpoints.

How to read the version number

Version numbers look like 2.20260721.0:

• 2 — Deribit API major version (v2)

• 20260721 — the publication date of the Deribit official documentation it aligns to (2026-07-21)

• 0 — the revision number under that documentation version

In other words, the middle segment tells you which day's Deribit documentation this version tracks. When Deribit updates its API, this project will bump the middle segment to the new date.

FAQ

The assistant says it can't find the Deribit tools? Check the client's MCP logs. At startup, the service prints the current environment, credential status, and the number of registered tools to stderr, so you can tell at a glance whether the configuration didn't take effect or something else is wrong.

You can only see market data tools, and all account tools are missing? That means the credentials weren't read. Make sure both DERIBIT_CLIENT_ID and DERIBIT_CLIENT_SECRET are configured — if only one is set, the service will fail to start and tell you which one is missing.

Can't see the trading tools? You need DERIBIT_ENABLE_TRADING=true and configured credentials. This is intentional default behavior.

Getting an invalid_credentials error? The key or secret is wrong, or you're using a testnet key while connected to mainnet (or vice versa). The two sides don't share accounts.

Getting an error saying insufficient scope? The API key doesn't have trade:read_write permission. The service will error out before placing the order, rather than making you think the order was already sent. Add the permission to the key in the Deribit dashboard, or turn off the trading switch.

Changed the configuration but it didn't take effect? The MCP service is started when the client launches, so you need to restart the client after changing environment variables.

License

MIT