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

Quick start — Local (Claude Desktop / Claude Code)

1. Get Deribit API keys

• Testnet (recommended to start): test.deribit.com/account/api
• Mainnet: deribit.com/account/api

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.

Clients & Related Projects

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