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.

📱 Multiple Messaging Options Available:

• This README: Telegram integration (with text messages AND phone calls with TTS)
• Signal Integration: Signal Messenger integration (privacy-focused, text messages only)

Both can run simultaneously! Choose based on your preferred messaging platform.

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

   Optional - For Phone Call Alerts:

   • Authorize CallMeBot: Visit https://api2.callmebot.com/txt/auth.php
   • Note your exact Telegram username (e.g., @yourname) from Settings → Edit Profile

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",
           "CALLMEBOT_USERNAME": "@yourname"
         }
       }
     }
   }
   

   Note: CALLMEBOT_USERNAME is optional - only needed for phone call alerts

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 messages, phone calls with text-to-speech, 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:

cd /path/to/mcp-server

2. Create a virtual environment:

python3 -m venv venv
source venv/bin/activate  # On macOS/Linux
# or
venv\Scripts\activate  # On Windows

3. Install dependencies:

pip3 install -e .

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

6. Configure CallMeBot (optional, for phone call alerts):

   a. Authorize CallMeBot (choose one method):

   Method 1 - Web Authorization (Recommended):

   • Visit: https://api2.callmebot.com/txt/auth.php
   • Log in with your Telegram account
   • Click "Authorize" to grant permissions
   • You'll see a success page with a test URL

   Method 2 - Telegram Bot:

   • Message @CallMeBot_API on Telegram (note: use @CallMeBot_API, not @CallMeBot_txtbot)
   • Send /start to authorize your account
   • Wait for confirmation message

   b. Get your Telegram username:

   • Your username is in the format @yourname (visible in Telegram Settings → Edit Profile)
   • Make sure to use the EXACT username shown in your Telegram profile
   • Alternatively, you can use your phone number in international format (e.g., +1234567890)

   c. Add to config:

   • Add CALLMEBOT_USERNAME to your Claude Desktop config (see next section)
   • Use the exact username from your Telegram profile (case-sensitive)
   • You can also customize the voice language with CALLMEBOT_DEFAULT_LANG (default: en-US-Standard-B)

Configuration

For Local Testing (Optional)

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

cp .env.example .env

Edit .env with your settings:

# Deribit API (optional - for account features)
DERIBIT_API_KEY=your_api_key_here
DERIBIT_API_SECRET=your_api_secret_here
DERIBIT_TEST_MODE=true  # Set to false for production

# Telegram Notifications
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
TELEGRAM_CHAT_ID=your_telegram_chat_id_here

# CallMeBot (Optional - for phone call alerts with TTS)
CALLMEBOT_USERNAME=@yourname  # Or phone number like +1234567890
CALLMEBOT_DEFAULT_LANG=en-US-Standard-B  # TTS voice/language
CALLMEBOT_REPEAT_COUNT=1  # Number of times to repeat the message

# Logging
LOG_LEVEL=INFO

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:

python -m src.server

With uv:

uv run python -m src.server

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.

{
  "mcpServers": {
    "deribit": {
      "command": "/absolute/path/to/mcp-server/venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/absolute/path/to/mcp-server",
      "env": {
        "DERIBIT_TEST_MODE": "true",
        "LOG_LEVEL": "INFO",
        "PYTHONUNBUFFERED": "1",
        "TELEGRAM_BOT_TOKEN": "your_telegram_bot_token_here",
        "TELEGRAM_CHAT_ID": "your_telegram_chat_id_here",
        "CALLMEBOT_USERNAME": "@yourname"
      }
    }
  }
}

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" (text message), "telegram_call" (phone call with TTS), or "console"
• message: Custom alert message (optional)
• repeat: Re-trigger after cooldown (default: false)

Examples:

Set a price alert for BTC-PERPETUAL above $100,000 via Telegram
Set a phone call alert for ETH-PERPETUAL below $3,000

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

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

Phone Call Alert

"Call me when BTC-PERPETUAL crosses above $105,000"
"Set a phone call alert for ETH-PERPETUAL below $3,000"

Crossing Alert

"Alert me when ETH-PERPETUAL crosses below $3,500"

Percentage Change

"Set a 5% change alert for BTC-PERPETUAL"

Check Current Price

"What's the current price of BTC-PERPETUAL?"

View Alerts

"Show me all my active alerts"

Account Management

"What's my BTC account balance?"
"Show my open positions"

Development

Project Structure

mcp-server/
├── src/                    # Telegram implementation
│   ├── __init__.py
│   ├── server.py          # Main MCP server (Telegram)
│   ├── config.py          # Configuration management
│   ├── deribit_ws.py      # WebSocket client
│   ├── deribit_rest.py    # REST API client
│   ├── alerts.py          # Alert management
│   └── notifications.py   # Notification system (Telegram)
├── src-signal/            # Signal Messenger implementation
│   ├── __init__.py
│   ├── server.py          # Main MCP server (Signal)
│   ├── config.py          # Configuration management (Signal)
│   ├── deribit_ws.py      # WebSocket client (shared)
│   ├── deribit_rest.py    # REST API client (shared)
│   ├── alerts.py          # Alert management (shared)
│   └── notifications.py   # Notification system (Signal)
├── pyproject.toml         # Project dependencies
├── .env.example           # Example environment config
├── README.md              # Telegram documentation
└── README-signal.md       # Signal documentation

Running Tests

pytest tests/

Code Formatting

black src/
ruff check src/

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

CallMeBot Phone Calls

If phone call alerts don't work:

1. Verify authorization:

   • Best method: Visit https://api2.callmebot.com/txt/auth.php and authorize with your Telegram account
   • Or send /start to @CallMeBot_API (not @CallMeBot_txtbot)
   • Check authorization status: curl "http://api.callmebot.com/start.php?user=@yourname&text=test"

2. Check username format:

   • Use EXACT format @yourname from Telegram Settings → Edit Profile
   • Username is case-sensitive and must match exactly
   • Or use international phone format like +1234567890
   • Common mistake: using wrong username (verify in Telegram app)

3. Check environment variable:

   • Make sure CALLMEBOT_USERNAME is set correctly in Claude Desktop config
   • Must match the username you authorized with CallMeBot
   • Restart Claude Desktop after changes

4. Check logs (macOS):

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

   • Look for "Telegram call channel initialized for @yourname" (good)
   • Look for "Successfully initiated call to @yourname" (call was sent)
   • Or "CallMeBot username not configured" (means env var not set)
   • Or "HTTP Request: GET http://api.callmebot.com/start.php" (shows API call)

5. Test with a simple alert:

   • Try: "Set a telegram_call alert for BTC-PERPETUAL above $1"
   • This should trigger immediately if price is above $1
   • Check logs to see if "Successfully initiated call" appears

Note: There's a known issue with audio playback on iOS Telegram app. Android and Desktop work better.

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