deribit-mcp
Provides tools to fetch TradingView chart data (OHLCV candlesticks) for any instrument.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@deribit-mcp show my portfolio summary and greeks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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 build3. 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
Go to railway.com and create a new project
Select Deploy from GitHub repo and connect
schoeffeljp/deribit-mcpRailway 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_hereRailway 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/mcp4. 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 |
| List all available currencies on Deribit |
| List tradable instruments (options, futures, spots) for a currency |
| Real-time quote with greeks, IV, bid/ask, mark price |
| Bid/ask depth for an instrument |
| Market-wide summary (volume, OI, prices) for all instruments |
| Current index price (e.g. btc_usd, eth_usd) |
| Historical volatility data points over time |
| DVOL (Deribit's VIX equivalent) OHLCV data |
| OHLCV candlestick data for any instrument |
| Perpetual funding rate history |
| Historical settlement/delivery prices |
Account & Trading (13 tools — private, requires auth)
Tool | Description |
| Balance, equity, margin usage, P&L |
| All open positions with greeks and P&L |
| Pending orders |
| Place orders (limit, market, stop). Use |
| Modify an existing order's price, amount, or parameters |
| Cancel orders |
| Flatten a position with market or limit |
| Trade fill history by currency, filterable by kind (option/future/spot) |
| Full fill history for a specific instrument — includes timestamp, index price, IV at trade time. Essential for position entry analysis |
| Full ledger (trades, settlements, fees, funding, deposits, withdrawals) |
| Estimate margin for a hypothetical trade before placing it |
Workflow Tools (6 tools — composite, chain multiple API calls into one)
Tool | Description |
| All available expiry dates with strike counts, sorted chronologically |
| Full chain for an expiry: all strikes with bid/ask, IV, greeks, OI for calls and puts |
| Find options closest to a target delta (e.g. "25-delta put") |
| IV matrix across all strikes and expirations with ATM IV and skew per expiry |
| Aggregated delta/gamma/vega/theta across all option positions |
| One-shot account overview: balances + all positions + all open orders |
Analytics Tools (3 tools — compute derived metrics for decision-making)
Tool | Description |
| 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 and IV percentile over a configurable lookback period, plus current HV and VRP signal |
| 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 |
| "Review my positions", "Should I close this?" | Calls |
| "Run a risk check", "How's my portfolio health?" | Calls |
| "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 |
| For private tools | — | Deribit API key ID |
| For private tools | — | Deribit API secret |
| No |
| Set |
| No |
|
|
| No |
| HTTP server port (Railway sets this automatically) |
| For HTTP mode | — | Bearer token for authentication |
| 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
/mcpendpoint 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_chainfetches 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_KEYin 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_ORIGINto 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 testDevelopment
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 testsSwitching 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
Available Tools
35 toolsanalyze_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
Scored across 35 tools
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.
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.
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).
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
Related MCP Connectors
AI agents backtest, paper trade and live trade via your broker. Free to connect; OAuth.
Unified financial infrastructure connecting AI agents directly to trade live/demo brokerage accounts, Web3 non-custodial wallets, real-time market data across equities, ETFs, crypto, forex, options, DeFi swaps, and prediction markets, institutional research feeds, and algorithmic strategy backtesters.
Connect brokerage accounts to AI assistants: holdings, orders, asset lookup, and approved trading.
Trade 16 crypto exchanges + MetaTrader 5 from your AI assistant via one MCP connection.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects a brokerage account to AI assistants, enabling portfolio queries, order management, and market data access through natural language.MIT
- AlicenseNot gradedqualityCmaintenanceConnects AI assistants to live options market data with 70+ tools for exposure analytics, volatility, strategy signals, and historical backtesting.1MIT
- FlicenseNot gradedqualityBmaintenanceConnects AI agents to real-time market data, options analysis, broker order staging, and automated alerts and workflows.-
- AlicenseAqualityCmaintenanceMCP 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).181MIT