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. ## 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) 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" } } } } ``` 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**: ```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 ## 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 # 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" } } } } ``` **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**: ``` Set a price alert for BTC-PERPETUAL above $100,000 via Telegram ``` ### `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" ``` ### 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/ │ ├── __init__.py │ ├── server.py # Main MCP server │ ├── config.py # Configuration management │ ├── deribit_ws.py # WebSocket client │ ├── deribit_rest.py # REST API client │ ├── alerts.py # Alert management │ └── notifications.py # Notification system ├── pyproject.toml # Project dependencies ├── .env.example # Example environment config └── README.md ``` ### 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 ## 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)