Deribit MCP Server

# 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](README-signal.md)**: 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**: ```bash python3 -m venv venv && source venv/bin/activate pip3 install -e . ``` 2. **Get Telegram credentials**: - Create a bot: Message [@BotFather](https://t.me/botfather), send `/newbot` - Get chat ID: Message [@userinfobot](https://t.me/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`: ```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**: ```bash cd /path/to/mcp-server ``` 2. **Create a virtual environment**: ```bash python3 -m venv venv source venv/bin/activate # On macOS/Linux # or venv\Scripts\activate # On Windows ``` 3. **Install dependencies**: ```bash 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](https://t.me/botfather) on Telegram - Send `/newbot` and follow the prompts - Save the bot token (e.g., `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`) b. **Get your Chat ID**: - Message [@userinfobot](https://t.me/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](https://t.me/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: ```bash cp .env.example .env ``` Edit `.env` with your settings: ```env # 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**: ```bash python -m src.server ``` **With uv**: ```bash 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. ```json { "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 ```bash pytest tests/ ``` ### Code Formatting ```bash 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): ```bash 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](https://t.me/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): ```bash 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](https://modelcontextprotocol.io) - Review [Deribit API docs](https://docs.deribit.com) - Open an issue on GitHub ## Acknowledgments - Built with [FastMCP](https://github.com/modelcontextprotocol/python-sdk) - Integrates with [Deribit Exchange](https://www.deribit.com) - Notifications via [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot)