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)

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

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

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

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.

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

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