Deribit MCP Server

# Deribit MCP Server (Signal Messenger) A Model Context Protocol (MCP) server that integrates with the Deribit cryptocurrency exchange, providing real-time price monitoring and intelligent alerts through Claude Desktop via **Signal Messenger**. ## Overview This MCP server enables Claude to monitor cryptocurrency prices on Deribit and send you instant Signal Messenger 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" - 📱 **Signal Notifications**: Receive instant text alerts on your phone via Signal Messenger - 📊 **Real-time Data**: WebSocket connections for live price feeds - 💼 **Account Management**: View balances, positions, and account summaries - 🔐 **Privacy-Focused**: Uses Signal Messenger for end-to-end encrypted notifications > **⚠️ Important Limitation:** Signal does NOT support phone calls or TTS (text-to-speech) through the CallMeBot API. Only **text messages** are available. For phone call alerts, use the [Telegram integration](README.md) instead. ## Quick Start 1. **Install dependencies**: ```bash python3 -m venv venv && source venv/bin/activate pip3 install -e . ``` 2. **Configure CallMeBot Signal API**: - Add contact: **+34 644 52 74 88** to your phone - Open Signal and send: **"I allow callmebot to send me messages"** - Wait for API key response - Note your phone number with country code (e.g., +1234567890) 3. **Configure Claude Desktop**: Edit `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "deribit-signal": { "command": "/path/to/mcp-server/venv/bin/python", "args": ["-m", "src-signal.server"], "cwd": "/path/to/mcp-server", "env": { "DERIBIT_TEST_MODE": "true", "SIGNAL_PHONE_NUMBER": "+1234567890", "SIGNAL_API_KEY": "your_api_key_from_callmebot" } } } } ``` 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 - **Signal Messenger Notifications**: Encrypted notifications via Signal - **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 (optional, for account operations) - Signal Messenger installed on your phone - CallMeBot API key for Signal ### Setup 1. **Clone or navigate to the repository**: ```bash cd /path/to/mcp-server ``` 2. **Create a virtual environment** (if not already done): ```bash python3 -m venv venv source venv/bin/activate # On macOS/Linux ``` 3. **Install dependencies**: ```bash pip3 install -e . ``` 4. **Configure CallMeBot Signal API**: a. **Add CallMeBot Contact**: - Add phone number **+34 644 52 74 88** to your contacts - Name it "CallMeBot" or similar b. **Authorize via Signal**: - Open Signal Messenger - Start a conversation with +34 644 52 74 88 - Send the message: **"I allow callmebot to send me messages"** - Wait for a response with your personal API key c. **Save your credentials**: - Your phone number with country code (e.g., +1234567890) - The API key provided by CallMeBot 5. **Configure Deribit API** (optional, for account features): - Go to https://www.deribit.com/account/api - Create API credentials with appropriate permissions ## 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 # Signal Messenger (via CallMeBot) SIGNAL_PHONE_NUMBER=+1234567890 # Your phone with country code SIGNAL_API_KEY=your_callmebot_api_key_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-signal.server ``` **With uv**: ```bash uv run python -m src-signal.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` ```json { "mcpServers": { "deribit-signal": { "command": "/absolute/path/to/mcp-server/venv/bin/python", "args": ["-m", "src-signal.server"], "cwd": "/absolute/path/to/mcp-server", "env": { "DERIBIT_TEST_MODE": "true", "LOG_LEVEL": "INFO", "PYTHONUNBUFFERED": "1", "SIGNAL_PHONE_NUMBER": "+1234567890", "SIGNAL_API_KEY": "your_api_key_here" } } } } ``` **Note**: - Use the full path to your virtual environment's Python executable - Include Signal 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`: "signal" (default) 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 Alert me via Signal when ETH-PERPETUAL crosses 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") ## 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" ``` ## Troubleshooting ### Signal Notifications If Signal notifications don't arrive: 1. **Verify CallMeBot Authorization**: - Make sure you sent "I allow callmebot to send me messages" to +34 644 52 74 88 - Check that you received an API key response 2. **Check phone number format**: - Use international format with country code (e.g., +1234567890) - No spaces or special characters except the leading + - Must match the number you used for CallMeBot authorization 3. **Check environment variables**: - Make sure `SIGNAL_PHONE_NUMBER` and `SIGNAL_API_KEY` are set in Claude Desktop config - Restart Claude Desktop after changes 4. **Check logs** (macOS): ```bash tail -f ~/Library/Logs/Claude/mcp-server-deribit.log ``` - Look for "Signal channel initialized" (good) - Look for "Successfully sent Signal message" (notification sent) - Or "Signal credentials not found" (means env vars not set) 5. **Test with a simple alert**: - Try: "Set a signal alert for BTC-PERPETUAL above $1" - This should trigger immediately if price is above $1 ### API Key Issues If you lost your API key: - Send "I allow callmebot to send me messages" again to +34 644 52 74 88 - You'll receive a new API key ## Signal vs Telegram **Advantages of Signal:** - ✅ End-to-end encrypted notifications - ✅ More privacy-focused - ✅ No bot account needed - ✅ Simple setup process **Limitations:** - ❌ **No phone call / TTS feature** (unlike Telegram) - Signal's architecture does not allow automated voice calls via API - ❌ Text messages only - ⚠️ Requires CallMeBot third-party service > **Why no calls?** Signal's design prioritizes privacy and security. All voice calls in Signal are peer-to-peer encrypted and require manual user initiation. No third-party service (including CallMeBot) can programmatically initiate voice calls through Signal's API or infrastructure. This is a fundamental architectural decision, not a limitation that can be worked around. ## Running Both Signal and Telegram You can run both implementations simultaneously! See the main README.md for Telegram setup. Configure both in your `claude_desktop_config.json`: ```json { "mcpServers": { "deribit-telegram": { "command": "/path/to/venv/bin/python", "args": ["-m", "src.server"], ... }, "deribit-signal": { "command": "/path/to/venv/bin/python", "args": ["-m", "src-signal.server"], ... } } } ``` ## 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. **CallMeBot**: API keys are tied to your phone number 5. **Signal Privacy**: Messages use CallMeBot as intermediary ## Support For issues and questions: - Check the [MCP documentation](https://modelcontextprotocol.io) - Review [Deribit API docs](https://docs.deribit.com) - Check [CallMeBot Signal API](https://www.callmebot.com/blog/free-api-signal-send-messages/) - 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 [CallMeBot Signal API](https://www.callmebot.com/) - Uses [Signal Messenger](https://signal.org/) for secure communications