Deribit MCP Server

A Model Context Protocol (MCP) server that integrates with the Deribit cryptocurrency exchange, providing real-time price monitoring and intelligent alerts through Claude Desktop.

Overview

This MCP server enables Claude to monitor cryptocurrency prices on Deribit and send you instant Telegram notifications when price conditions are met. Set alerts for BTC, ETH, and other instruments using natural language in Claude Desktop.

Key Capabilities:

• 🔔 Smart Price Alerts: Set alerts using conditions like "above", "below", "crosses above/below", or "percentage change"

• 📱 Telegram Notifications: Receive instant alerts on your phone via Telegram

• 📊 Real-time Data: WebSocket connections for live price feeds

• 💼 Account Management: View balances, positions, and account summaries

• 🔄 Live Monitoring: Continuous price tracking with automatic alert triggering

Quick Start

1. Install dependencies:

   python3 -m venv venv && source venv/bin/activate pip3 install -e .

2. Get Telegram credentials:

   • Create a bot: Message @BotFather, send /newbot

   • Get chat ID: Message @userinfobot

3. Configure Claude Desktop: Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

   { "mcpServers": { "deribit": { "command": "/path/to/mcp-server/venv/bin/python", "args": ["-m", "src.server"], "cwd": "/path/to/mcp-server", "env": { "DERIBIT_TEST_MODE": "true", "TELEGRAM_BOT_TOKEN": "your_bot_token", "TELEGRAM_CHAT_ID": "your_chat_id" } } } }

4. Restart Claude Desktop and try:

   "Set an alert for BTC-PERPETUAL when it goes above $100,000"

Features

• Real-time Price Monitoring: WebSocket connection for live price feeds

• Price Alerts: Configurable alerts with multiple condition types

• Multi-channel Notifications: Telegram, console, and extensible notification system

• Account Management: View balances, positions, and account summary

• Trading Information: Access to instruments, order books, and market data

• MCP Integration: Full compatibility with Claude Desktop and other MCP clients

Installation

Prerequisites

• Python 3.10 or higher

• Deribit API credentials (for account operations)

• Telegram Bot Token (for notifications)

Setup

1. Clone or navigate to the repository:

2. Create a virtual environment:

3. Install dependencies:

4. Configure Deribit API (optional, for account features):

   • Go to https://www.deribit.com/account/api

   • Create API credentials with appropriate permissions

   • Note: You'll add these to your Claude Desktop config later

5. Configure Telegram Bot (for notifications):

   a. Create a bot:

   • Message @BotFather on Telegram

   • Send /newbot and follow the prompts

   • Save the bot token (e.g., 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

   b. Get your Chat ID:

   • Message @userinfobot on Telegram

   • It will reply with your user info including your chat ID

   • Or send a message to your bot, then visit:

     https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

   • Look for "chat":{"id":123456789} in the response

   c. Save credentials:

   • You'll add these to your Claude Desktop config in the next step

Configuration

For Local Testing (Optional)

If you want to run the server directly (not through Claude Desktop), create a .env file:

Edit .env with your settings:

Note: The .env file is only used for local development/testing. For Claude Desktop integration, you must include these values in the claude_desktop_config.json file (see next section).

Usage

Running the Server

Direct execution:

With uv:

Claude Desktop Integration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Important: When using Claude Desktop, you must include ALL environment variables (including Telegram credentials) in the env section, as the .env file is not automatically loaded.

Note:

• Use the full path to your virtual environment's Python executable

• Include Telegram credentials directly in the config for notifications to work

• Set DERIBIT_TEST_MODE to false for production trading

• Optionally add DERIBIT_API_KEY and DERIBIT_API_SECRET to the env section for account features

Available Tools

set_price_alert

Create a price alert for an instrument.

Parameters:

• instrument: Trading instrument (e.g., "BTC-PERPETUAL")

• condition: Alert type - "above", "below", "crosses_above", "crosses_below", "percentage_change"

• threshold: Price level or percentage

• notification_channel: "telegram" or "console"

• message: Custom alert message (optional)

• repeat: Re-trigger after cooldown (default: false)

Example:

remove_alert

Remove an existing alert.

Parameters:

• alert_id: Alert ID to remove

list_alerts

List all configured alerts with optional filtering.

Parameters:

• instrument: Filter by instrument (optional)

• status: Filter by status (optional)

get_current_price

Get the current price for an instrument.

Parameters:

• instrument: Trading instrument

get_instruments

List available trading instruments.

Parameters:

• currency: Currency code (default: "BTC")

• kind: "future", "option", or "spot"

get_account_summary

View account balance and equity.

Parameters:

• currency: Currency code (default: "BTC")

get_positions

List all open positions.

Parameters:

• currency: Currency code (default: "BTC")

Resources

deribit://price/{instrument}

Real-time price data for an instrument.

deribit://alerts

JSON list of all configured alerts.

deribit://account/{currency}

Account summary information.

Alert Conditions

1. above: Triggers when price goes above threshold

2. below: Triggers when price goes below threshold

3. crosses_above: Triggers when price crosses up through threshold

4. crosses_below: Triggers when price crosses down through threshold

5. percentage_change: Triggers on percentage change from last check

Example Use Cases

Basic Price Monitoring

Crossing Alert

Percentage Change

Check Current Price

View Alerts

Account Management

Development

Project Structure

Running Tests

Code Formatting

Security Considerations

1. API Credentials: Never commit .env file to version control

2. Test Mode: Use DERIBIT_TEST_MODE=true for testing

3. Permissions: Limit Deribit API permissions to minimum required

4. Notifications: Secure your Telegram bot token

Troubleshooting

Connection Issues

If WebSocket connection fails:

• Check internet connectivity

• Verify Deribit API status

• Try test environment first (DERIBIT_TEST_MODE=true)

Authentication Errors

If API authentication fails:

• Verify API key and secret

• Check API key permissions on Deribit

• Ensure credentials are in .env file

Telegram Notifications

If notifications don't arrive:

1. Check environment variables in Claude Desktop config:

   • Most common issue: Telegram credentials not in claude_desktop_config.json

   • The .env file is NOT read by Claude Desktop

   • You MUST add TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID to the env section of your config

2. Verify credentials:

   • Check bot token is correct

   • Check chat ID is correct (should be a number like 1950437710)

   • Send a message to your bot first (so it knows your chat ID)

3. Check logs (macOS):

   tail -f ~/Library/Logs/Claude/mcp-server-deribit.log

   • Look for "Initialized Telegram notification channel" (good)

   • Or "Telegram credentials not found" (means env vars not set correctly)

4. Test notification on startup:

   • When the server starts, it sends a test message

   • If you receive this, Telegram is configured correctly

   • If not, check your Claude Desktop config

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

• Check the MCP documentation

• Review Deribit API docs

• Open an issue on GitHub

Acknowledgments

• Built with FastMCP

• Integrates with Deribit Exchange

• Notifications via python-telegram-bot