Skip to main content
Glama
deribit-mcp

deribit-mcp

by schoeffeljp

Deribit MCP — Crypto Options Trading Companion

An MCP (Model Context Protocol) server that turns any AI assistant into a crypto options trading companion. Connects to Deribit for real-time market data, portfolio management, trade execution, and risk analysis — all through natural language.

Beyond raw API access, it includes analytical tools (fee-aware P&L, IV rank, portfolio risk metrics), workflow tools (options chains, volatility surfaces), and built-in skills (position management, risk assessment, strategy scanning) that any MCP client can discover and use automatically.

Works with Claude Desktop, Claude Code, Stack AI, or any MCP-compatible client. Supports both stdio (local) and HTTP (remote/cloud) transports.

What you can do

  • Explore the options market — list expirations, pull full options chains with greeks and IV, scan the volatility surface across all strikes and expiries

  • Find opportunities — search by delta, compare implied vs historical vol (IV rank, VRP), check funding rates, scan for high-yield trades

  • Trade — place/edit/cancel orders, close positions, estimate margin before trading

  • Monitor your portfolio — one-shot account overview, aggregated greeks, full trade history per instrument with fees

  • Analyze positions — fee-aware net P&L (including entry fees, exit simulation with bid/ask spread and taker fees), DTE-based risk flags, automated HOLD/CLOSE/ROLL recommendations

  • Manage risk — Tasty Trade-style portfolio metrics (theta/netliq, delta/theta ratio, margin utilization, concentration), buying power analysis

  • Get strategy advice — naked put, strangle, covered call, and calendar spread scanning with complete trade plans

Related MCP server: FlashAlpha MCP Server

Quick start — Local (Claude Desktop / Claude Code)

1. Get Deribit API keys

You need read + trade scopes for full functionality. Public market data works without credentials.

2. Clone and build

git clone https://github.com/schoeffeljp/deribit-mcp.git
cd deribit-mcp
npm install
npm run build

3. Add to Claude Desktop

Edit your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "deribit": {
      "command": "node",
      "args": ["/absolute/path/to/deribit-mcp/dist/index.js"],
      "env": {
        "DERIBIT_CLIENT_ID": "your_client_id",
        "DERIBIT_CLIENT_SECRET": "your_client_secret",
        "DERIBIT_TESTNET": "true"
      }
    }
  }
}

Restart Claude Desktop. The Deribit tools, analytics, and skills will appear automatically.

Quick start — Cloud (Railway)

Deploy to Railway for remote access from Stack AI, custom apps, or any HTTP-based MCP client. Takes under 5 minutes.

1. Create a Railway project

  1. Go to railway.com and create a new project

  2. Select Deploy from GitHub repo and connect schoeffeljp/deribit-mcp

  3. Railway auto-detects Node.js, runs npm run build, and starts the server

2. Set environment variables

In the Railway service Variables tab, add:

DERIBIT_CLIENT_ID=your_client_id
DERIBIT_CLIENT_SECRET=your_client_secret
DERIBIT_TESTNET=false
MCP_TRANSPORT=http
MCP_API_KEY=generate_a_random_secret_here

Railway auto-sets PORT. The server will start in HTTP mode automatically.

3. Get your public URL

Railway assigns a URL like https://your-service.up.railway.app. Your MCP endpoint is:

https://your-service.up.railway.app/mcp

4. Connect your MCP client

Stack AI: Add a new MCP connection (API Key type), enter your Railway URL + API key.

Any MCP client:

{
  "mcpServers": {
    "deribit": {
      "type": "streamable-http",
      "url": "https://your-service.up.railway.app/mcp",
      "headers": {
        "Authorization": "Bearer your_mcp_api_key"
      }
    }
  }
}

Custom app (using MCP SDK):

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "my-app" });
await client.connect(new StreamableHTTPClientTransport(
  new URL("https://your-service.up.railway.app/mcp"),
  { headers: { Authorization: "Bearer your_mcp_api_key" } }
));

// Discover all tools automatically
const { tools } = await client.listTools();

// Discover all skills (prompts) automatically
const { prompts } = await client.listPrompts();

// Call any tool
const result = await client.callTool({
  name: "get_options_chain",
  arguments: { currency: "USDC", underlying: "ETH", expiry: "24APR26" }
});

That's it. Every push to GitHub auto-deploys to Railway.

Tools

Market Data (12 tools — public, no auth needed)

Tool

Description

get_currencies

List all available currencies on Deribit

get_instruments

List tradable instruments (options, futures, spots) for a currency

get_ticker

Real-time quote with greeks, IV, bid/ask, mark price

get_order_book

Bid/ask depth for an instrument

get_book_summary_by_currency

Market-wide summary (volume, OI, prices) for all instruments

get_index_price

Current index price (e.g. btc_usd, eth_usd)

get_historical_volatility

Historical volatility data points over time

get_volatility_index

DVOL (Deribit's VIX equivalent) OHLCV data

get_tradingview_chart_data

OHLCV candlestick data for any instrument

get_funding_rate_history

Perpetual funding rate history

get_delivery_prices

Historical settlement/delivery prices

Account & Trading (13 tools — private, requires auth)

Tool

Description

get_account_summary

Balance, equity, margin usage, P&L

get_positions

All open positions with greeks and P&L

get_open_orders

Pending orders

buy / sell

Place orders (limit, market, stop). Use amount (base currency) or contracts

edit_order

Modify an existing order's price, amount, or parameters

cancel_order / cancel_all_orders

Cancel orders

close_position

Flatten a position with market or limit

get_user_trades

Trade fill history by currency, filterable by kind (option/future/spot)

get_user_trades_by_instrument

Full fill history for a specific instrument — includes timestamp, index price, IV at trade time. Essential for position entry analysis

get_transaction_log

Full ledger (trades, settlements, fees, funding, deposits, withdrawals)

get_margins

Estimate margin for a hypothetical trade before placing it

Workflow Tools (6 tools — composite, chain multiple API calls into one)

Tool

Description

get_expirations

All available expiry dates with strike counts, sorted chronologically

get_options_chain

Full chain for an expiry: all strikes with bid/ask, IV, greeks, OI for calls and puts

find_options_by_delta

Find options closest to a target delta (e.g. "25-delta put")

get_volatility_surface

IV matrix across all strikes and expirations with ATM IV and skew per expiry

get_portfolio_greeks

Aggregated delta/gamma/vega/theta across all option positions

get_portfolio_summary

One-shot account overview: balances + all positions + all open orders

Analytics Tools (3 tools — compute derived metrics for decision-making)

Tool

Description

analyze_position

Fee-aware position analysis. Returns gross P&L, net P&L (after actual entry fees from trade history), simulated exit P&L (at bid/ask with taker fees), DTE, moneyness, greeks, risk flags, and HOLD/CLOSE/ROLL/TAKE_PROFIT recommendation

iv_rank

IV rank and IV percentile over a configurable lookback period, plus current HV and VRP signal

portfolio_risk_metrics

Portfolio-level dollar greeks, theta/netliq ratio, delta/theta ratio, margin utilization, position concentration, and per-position breakdown with sizing flags

Skills (MCP Prompts)

Skills are built-in prompt templates registered on the MCP server. Any client that supports prompts/list and prompts/get discovers them automatically — no client-side configuration needed. They combine the right tool calls with a structured analysis framework.

Skill

Trigger

What it does

position_management

"Review my positions", "Should I close this?"

Calls analyze_position, applies profit-taking rules (scale-out at 30/50/75%), DTE-based stops, delta exits, rolling framework. All recommendations use net P&L after fees and spread

risk_management

"Run a risk check", "How's my portfolio health?"

Calls portfolio_risk_metrics, evaluates Tasty Trade ratios (theta/netliq 0.1-0.3%, delta/theta < 0.5, margin < 50%), flags breaches, suggests remediation

strategy_advisor

"Find me a naked put", "Scan for strangles"

Accepts strategy type (naked_put / strangle / covered_call / calendar). Checks IV rank, scans candidates, ranks by yield, outputs complete trade plans with entry/stop/target/margin

How skills work

Skills live entirely on the MCP server. When a client calls prompts/list, it gets:

[
  { "name": "position_management", "description": "Systematic position review with risk flags..." },
  { "name": "risk_management", "description": "Portfolio-level risk assessment..." },
  { "name": "strategy_advisor", "description": "Trade idea generation..." }
]

The client fetches a skill with prompts/get("position_management") and receives a structured prompt that tells the LLM exactly which tools to call and how to analyze the results. The client doesn't need to know anything about options trading — the skill contains the complete framework.

Position management rules (built into the skill)

Profit taking (scale-out approach):

  • +50% profit: close 1/3 to 1/2 of contracts

  • Remaining: tighten stop to breakeven

  • +75% profit: close remaining

DTE-based stops (tighten as expiry approaches):

  • > 21 DTE: stop at -40% | 14-21 DTE: -35% | 7-14 DTE: -25% | < 7 DTE: -20% | < 3 DTE: close all

Fee awareness: all P&L calculations include actual entry fees (from trade history) and simulated exit costs (bid/ask spread + ~$0.9/contract taker fee). A position showing +11% gross might only be +2% net.

Example prompts

Once configured, try asking your AI assistant:

Market data:

  • "Show me all ETH option expirations"

  • "Get the full options chain for ETH USDC April 24th expiry"

  • "What's the BTC volatility surface?"

  • "Compare 30-day historical volatility with implied volatility for ETH"

Portfolio:

  • "Show me my positions with greeks"

  • "What's my net delta and theta exposure?"

  • "Pull the trade history for my ETH 2400 calls — when did I open them and at what underlying price?"

Analysis (triggers skills automatically):

  • "Review my positions and tell me what to close or hold"

  • "Run a risk check on my portfolio"

  • "Find me the best naked put opportunity on ETH right now"

  • "Scan for short strangles on ETH with IV rank above 50"

Trading:

  • "Buy 0.05 ETH of the 2400 call for April at limit price $25"

  • "Close my 1950 put position at market"

  • "How much margin would I need for 3 contracts of the 2000 put?"

Environment variables

Variable

Required

Default

Description

DERIBIT_CLIENT_ID

For private tools

—

Deribit API key ID

DERIBIT_CLIENT_SECRET

For private tools

—

Deribit API secret

DERIBIT_TESTNET

No

false

Set true for testnet

MCP_TRANSPORT

No

stdio

stdio for local, http for cloud

PORT

No

3000

HTTP server port (Railway sets this automatically)

MCP_API_KEY

For HTTP mode

—

Bearer token for authentication

MCP_CORS_ORIGIN

No

*

Allowed CORS origin for HTTP mode

Architecture

src/
├── index.ts              # Entry — stdio or HTTP transport based on MCP_TRANSPORT
├── deribit-client.ts     # JSON-RPC client with auto-auth
├── prompts.ts            # Skills (position management, risk, strategy advisor)
└── tools/
    ├── public.ts         # 12 market data tools (no auth)
    ├── private.ts        # 13 account & trading tools (auth required)
    ├── workflow.ts       # 6 composite tools (chain multiple API calls)
    └── analytics.ts      # 3 analytical tools (derived metrics, risk scoring)

Two transport modes:

  • stdio (default) — Claude Desktop spawns and manages the process. Zero setup.

  • HTTP — standalone server with /mcp endpoint using Streamable HTTP transport. Deploy anywhere.

Key design decisions:

  • Workflow tools compose multiple Deribit API calls into a single tool call (e.g. get_options_chain fetches instruments + tickers for all strikes)

  • Analytics tools compute derived metrics (net P&L after fees, IV rank, portfolio risk ratios) that raw API data doesn't provide

  • Skills are MCP prompts — they live on the server and are auto-discovered by any client. No client-side setup needed.

  • USDC-settled instruments are listed under currency: "USDC", not under "ETH" or "BTC" — this is a Deribit API quirk that the tools handle transparently

Security

  • Always set MCP_API_KEY in HTTP mode. Without it, anyone who finds the URL can use your Deribit credentials.

  • Never expose Deribit credentials in client-side code. The MCP server holds them server-side.

  • Set MCP_CORS_ORIGIN to your app's domain in production.

  • Trading tools place real orders. Use testnet first.

Running tests

# Public endpoint tests (no credentials needed)
npm test

# With valid testnet credentials, private endpoint tests also run
DERIBIT_CLIENT_ID=xxx DERIBIT_CLIENT_SECRET=yyy npm test

Development

npm run dev          # Watch mode — recompiles on changes
npm run build        # One-time build
npm test             # Run test suite
npm run test:watch   # Watch mode for tests

Switching to mainnet

Set DERIBIT_TESTNET=false in your .env or Claude Desktop config. Use mainnet with caution — trading tools place real orders with real money.

This MCP server is designed to work with any MCP-compatible client. Here are purpose-built companions:

  • deribit-telegram-agent — Conversational Telegram bot powered by Claude. Connects to this MCP server as a client for two-way trading, portfolio analysis, and strategy discussion on the go.

License

MIT

Available Tools

35 tools
analyze_positionA

PREFERRED tool for position analysis — returns fee-aware NET P&L (after actual entry fees from trade history + estimated exit fees at ~$0.9/contract taker), realistic exit simulation at bid/ask (not mark), DTE, greeks, moneyness, risk flags, and HOLD/TAKE_PROFIT/CLOSE/ROLL recommendations. Always use this instead of get_positions + get_ticker when analyzing positions.

Inputs: currency (required), instrument_name.

buyA

Place a buy order on Deribit. Supports limit, market, stop_limit, and stop_market order types. Use with caution — this places a real trade.

Inputs: instrument_name (required), type, label, price, +5 more.

cancel_all_ordersA

Cancel all open orders, optionally filtered by currency and instrument type.

Inputs: kind, currency.

cancel_orderA

Cancel an open order by its order ID.

Inputs: order_id (required).

close_positionA

Close an existing position entirely. Places a market or limit order to flatten the position.

Inputs: type (required), instrument_name (required), price.

edit_orderA

Modify an existing open order's price, amount, or other parameters without cancelling and re-placing.

Inputs: order_id (required), price, amount, contracts, +3 more.

find_options_by_deltaA

Find options closest to a target delta for a given currency and expiry. E.g., 'find the 25-delta put' or 'find the 50-delta call'. Returns the best matching options sorted by delta proximity.

Inputs: expiry (required), currency (required), target_delta (required), num_results.

get_account_summaryA

Get account balance, equity, margin usage, and P&L summary for a currency.

Inputs: currency (required), extended.

get_book_summary_by_currencyA

Get summary info (volume, open interest, bid/ask, mark price) for all instruments of a currency. Useful for scanning the entire options or futures market at a glance.

Inputs: currency (required), kind.

get_currenciesA

List all available currencies on Deribit

Inputs: no named parameters.

get_delivery_pricesB

Get historical settlement/delivery prices for an index. Useful for backtesting and understanding past expiry outcomes.

Inputs: index_name (required), count, offset.

get_expirationsA

List available option expiration dates for a currency, sorted chronologically. For USDC currency, use 'underlying' to filter ETH vs BTC options.

Inputs: currency (required), max_dte, underlying.

get_funding_rate_historyA

Get historical funding rate data for a perpetual instrument. Shows hourly funding rates, index prices, and interest rates.

Inputs: end_timestamp (required), instrument_name (required), start_timestamp (required).

get_historical_volatilityB

Get historical volatility data points for a currency index over time.

Inputs: currency (required).

get_index_priceA

Get the current index price for a given underlying index (e.g. btc_usd, eth_usd).

Inputs: index_name (required).

get_instrumentsA

List tradable instruments (options, futures, spots) for a currency. Returns instrument names, strike prices, expiration dates, and contract details. Essential for discovering available options chains.

Inputs: currency (required), kind, expired.

get_marginsA

Estimate the margin required for a hypothetical trade before placing it. Returns margin for both buy and sell sides, plus min/max price bounds.

Inputs: price (required), amount (required), instrument_name (required).

get_open_ordersB

List all open (unfilled) orders, optionally filtered by currency or instrument type.

Inputs: currency (required), kind.

get_options_chainA

Get options chain for a specific currency + expiry. Returns strikes with bid/ask, mark price, IV, greeks, OI. IMPORTANT: always specify 'underlying' for USDC currency, and use 'atm_range' to limit strikes (default 10 = ATM ± 10).

Inputs: expiry (required), currency (required), atm_range, underlying.

get_order_bookA

Get the order book (bids and asks) for an instrument, including best bid/ask, mark price, and funding rate for perpetuals.

Inputs: instrument_name (required), depth.

get_order_stateA

Get the current state of an order by its order_id. Returns order_state (open, filled, cancelled, rejected, untriggered), average_price, filled_amount, price, and all order details. Use this to check if an order was filled, partially filled, or cancelled.

Inputs: order_id (required).

get_portfolio_greeksA

Get aggregated portfolio greeks across all open option positions for a currency. Shows total delta, gamma, vega, and theta exposure, plus per-position breakdown. Essential for understanding net risk.

Inputs: currency (required).

get_portfolio_summaryA

One-shot overview of your entire account for a currency: balances, margin usage, equity, all open positions with P&L, and all open orders. Saves multiple API calls into a single comprehensive snapshot.

Inputs: currency (required).

get_positionsA

Get all open positions, including size, direction, P&L, average price, and greeks for options.

Inputs: currency (required), kind.

get_tickerA

Get real-time quote data for an instrument. For options, includes greeks (delta, gamma, vega, theta, rho), implied volatility, mark price, bid/ask, open interest, and volume.

Inputs: instrument_name (required).

get_tradingview_chart_dataA

Get OHLCV candlestick data for any instrument. Useful for price charts, technical analysis, and historical price research.

Inputs: resolution (required), end_timestamp (required), instrument_name (required), start_timestamp (required).

get_transaction_logC

Get the full ledger of account transactions: trades, settlements, fees, funding payments, deposits, withdrawals, and transfers.

Inputs: currency (required), end_timestamp (required), start_timestamp (required), count, +2 more.

get_user_tradesA

Get recent trade fills for a currency. ALWAYS filter by kind (option, future, spot) to narrow results. Shows price, size, fees, P&L, IV, and underlying price. Use get_user_trades_by_instrument if you know the specific instrument name.

Inputs: currency (required), kind, count, sorting, +2 more.

get_user_trades_by_instrumentA

Get trade history for a SPECIFIC instrument. Preferred when you know the instrument name (e.g. 'show me my fills on ETH_USDC-27MAR26-2400-C'). Returns price, size, fees, underlying price and IV at time of trade.

Inputs: instrument_name (required), count, sorting, end_timestamp, +1 more.

get_volatility_indexB

Get DVOL (Deribit Volatility Index) OHLCV data — Deribit's equivalent of the VIX. Shows implied volatility trend over time.

Inputs: currency (required), resolution (required), end_timestamp (required), start_timestamp (required).

get_volatility_surfaceA

Get the implied volatility surface across all strikes and expirations for a currency. Returns a matrix of expiry × strike → IV, plus ATM IV and skew metrics per expiry. Essential for relative value analysis and vol trading.

Inputs: currency (required).

iv_rankA

Get IV Rank, IV Percentile, HV30, and Volatility Risk Premium (VRP) for a cryptocurrency. IV Rank > 50 = rich (good for selling premium), < 30 = cheap (good for buying).

Inputs: currency (required), period.

portfolio_risk_metricsA

Portfolio-level risk dashboard with dollar greeks, theta/netliq ratio, delta/theta ratio, margin utilization, concentration per underlying, and health status (HEALTHY/CAUTION/AT_RISK). Based on Tasty Trade risk framework.

Inputs: currency (required).

scan_candidatesA

Scan for option trading opportunities by strategy (naked_put, strangle, covered_call). Returns ranked candidates with premium, delta, IV, margin, annualized yield, and position sizing recommendations.

Inputs: currency (required), strategy (required), max_dte, min_dte, +2 more.

sellA

Place a sell order on Deribit. Supports limit, market, stop_limit, and stop_market order types. Use with caution — this places a real trade.

Inputs: instrument_name (required), type, label, price, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 35 tools

    Disambiguation4/5

    Most tools target a distinct resource or action, with clear separation between market data, account/position data, order management, and options analytics. A few analytical tools (get_positions, analyze_position, get_portfolio_summary, portfolio_risk_metrics) have overlapping position/risk information, but the descriptions do enough to differentiate their intended use.

    Naming Consistency4/5

    The majority of tools follow a predictable get_<noun> or <verb>_<noun> pattern, which makes navigation straightforward. Minor deviations like iv_rank and portfolio_risk_metrics break the verb-oriented convention slightly, and get_tradingview_chart_data mixes a brand into an otherwise clean naming scheme.

    Tool Count2/5

    35 tools is a large surface for an MCP server, exceeding the 25+ threshold where the set starts feeling heavy for agent tool selection. While the domain is broad, several tools could be consolidated (e.g., the volatility-related tools and the position/portfolio analytics tools).

    Completeness4/5

    The tool set covers the core trading lifecycle well: market data, order placement/management, positions, fills, account summaries, and advanced options/risk analytics. Minor gaps remain, such as no multi-leg strategy order placement despite strategy scanning being offered, and no historical order search beyond open orders and trade fills.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects a brokerage account to AI assistants, enabling portfolio queries, order management, and market data access through natural language.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects AI assistants to live options market data with 70+ tools for exposure analytics, volatility, strategy signals, and historical backtesting.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for Deribit's crypto options exchange, enabling AI assistants to query market data, manage accounts and orders, and execute trades with safety defaults (testnet, trading disabled by default).
      18
      1
      MIT