Which integrations are available for this server?

Provides comprehensive trading and market data tools for the Derive API by Lyra Finance, enabling real-time market data access, historical data queries, options/perpetuals/spot trading, account management, and risk monitoring on Ethereum-based derivatives markets.

How do I use Derive MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Derive MCP show me my open positions and current PnL" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Derive

A comprehensive Model Context Protocol (MCP) server for the Derive API by Lyra Finance. This server provides 31+ tools to access real-time market data, historical data, trading capabilities, and account management for options, perpetuals, and spot trading.

Features

Real-time Market Data (Low Latency)

get_ticker - Real-time prices, bid/ask, volume, Greeks for single instruments
get_tickers - Multi-instrument ticker data efficiently
get_orderbook - Order book with configurable depth and spread analysis
get_currencies - All available trading pairs
get_instruments - Comprehensive instrument data with fees and constraints

Tick-by-Tick Historical Data

get_trade_history - Complete trade history with filtering and pagination
get_funding_rate_history - Perpetual funding rates with timestamps
get_spot_feed_history - Index price feed data
get_option_settlement_history - Option expiration and settlement data
get_liquidation_history - Platform liquidation events

Account Management

get_account - Account details, subaccounts, rate limits, fees
get_subaccounts - All subaccounts with labels
get_balance - Total balance across subaccounts and collaterals
get_positions - Open positions with PnL, Greeks, liquidation prices
get_collaterals - Collateral information and valuations
get_margin - Detailed margin metrics and status

Trading (All Instruments)

place_order - Market or limit orders for options, perps, and spot
cancel_order - Cancel individual orders
cancel_all_orders - Bulk cancel with filtering
replace_order - Atomic order replacement
get_open_orders - All open orders
get_orders_history - Complete order history with fills

Trade & Account History

get_my_trades - Personal trade history with fees and PnL
get_funding_history - Funding payments paid/received
get_deposit_history - Deposit transactions
get_withdrawal_history - Withdrawal transactions

RFQ (Request For Quote)

send_rfq - Request quotes from market makers
get_rfqs - View active RFQs
execute_quote - Execute at quoted prices

Risk Management

get_liquidation_price - Current liquidation price for positions
margin_watch - Accounts approaching liquidation

Installation

git clone <repo-url> mcp-derive
cd mcp-derive
npm install

Configuration

Environment Variables

# API Environment (mainnet or testnet)
DERIVE_ENVIRONMENT=mainnet

# Ethereum wallet address
DERIVE_WALLET=0x1234567890abcdef1234567890abcdef12345678

# Private key for transaction signing (optional, needed for trading)
DERIVE_PRIVATE_KEY=0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

Setup with Claude Desktop

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "derive": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-derive/index.js"],
      "env": {
        "DERIVE_ENVIRONMENT": "testnet",
        "DERIVE_WALLET": "0x...",
        "DERIVE_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Setup with Claude Code CLI

claude mcp add derive
# When prompted:
# - Command: node
# - Arguments: /absolute/path/to/mcp-derive/index.js
# - Environment variables:
#   - DERIVE_ENVIRONMENT=testnet
#   - DERIVE_WALLET=0x...
#   - DERIVE_PRIVATE_KEY=0x...

API Endpoints

Mainnet

HTTP: https://api.lyra.finance
WebSocket: wss://api.lyra.finance/ws (not yet supported by MCP)

Testnet

HTTP: https://api-demo.lyra.finance
WebSocket: wss://api-demo.lyra.finance/ws (not yet supported by MCP)

Tool Documentation

Public Market Data Tools

get_currencies

Get all available currencies on the platform.

Usage: Get all currencies to find available trading pairs

get_instruments

Get tradeable instruments for a specific currency and type.

Parameters:
  - currency (required): BTC, ETH, SOL, etc.
  - instrument_type (required): erc20, option, perp
  - expired (optional): Include expired instruments (default: false)

Response: Array of instruments with:
  - Fees (maker/taker rates)
  - Price constraints (min/max amounts, tick size)
  - For options: Strike, expiry, Greeks
  - For perps: Funding rate, interest rates

get_ticker

Real-time ticker for a single instrument.

Parameters:
  - instrument_name (required): e.g., BTC-PERP, ETH-20250131-3000-C

Response:
  - Best bid/ask with amounts
  - Last price, 24h volume, open interest
  - Greeks (for options): delta, gamma, vega, theta, rho
  - Mark price vs index price

get_tickers

Get tickers for multiple instruments (more efficient than get_ticker).

Parameters:
  - currency (optional): Filter by currency
  - instrument_type (optional): erc20, option, or perp

get_orderbook

Real-time order book with depth and spread analysis.

Parameters:
  - instrument_name (required): Instrument to get book for
  - depth (optional): Number of price levels (default 10, max 100)

Response:
  - Bid side: prices, amounts, cumulative
  - Ask side: prices, amounts, cumulative
  - Spread and mid-price

Historical Data Tools

get_trade_history

Tick-by-tick trade history across the platform.

Parameters:
  - instrument_name (optional): Filter by instrument
  - currency (optional): Filter by currency
  - instrument_type (optional): erc20, option, perp
  - from_timestamp (optional): Start time (ms)
  - to_timestamp (optional): End time (ms)
  - page (optional): Page number (default 1)
  - page_size (optional): Results per page (default 100, max 1000)
  - trade_id (optional): Get specific trade
  - tx_hash (optional): Get by transaction hash
  - tx_status (optional): settled, reverted, timed_out

Response: Trade details including:
  - Price, amount, side (buy/sell)
  - Buyer/seller addresses
  - Timestamp, transaction hash
  - Rebates and fees

get_funding_rate_history

Historical funding rates for perpetual contracts.

Parameters:
  - instrument_name (optional): e.g., BTC-PERP
  - currency (optional): Filter by currency
  - from_timestamp (optional): Start time
  - to_timestamp (optional): End time
  - Pagination parameters

Response: Historical funding events with:
  - Timestamp
  - Funding rate
  - Cumulative funding

get_spot_feed_history

Historical index prices (spot feeds).

Parameters:
  - currency (required): BTC, ETH, etc.
  - from_timestamp, to_timestamp: Time range
  - Pagination parameters

Response: Historical price data with timestamps

get_option_settlement_history

Option expiration and settlement data.

Response:
  - Strike price
  - Settlement price (determined at expiration)
  - Settlement timestamp
  - Option type (call/put)

get_liquidation_history

Platform-wide liquidation events.

Parameters:
  - currency (optional): Filter by currency
  - instrument_name (optional): Filter by instrument
  - Time range parameters
  - Pagination

Response: Liquidation events showing:
  - Which positions were liquidated
  - Liquidation price vs mark price
  - Amount liquidated

Account Management Tools

get_account

Account overview with rate limits and fees.

Response:
  - Subaccount IDs
  - Rate limits (TPS by operation type)
  - Fee structure
  - Account settings (cancel on disconnect, RFQ eligibility)
  - Referral code

get_subaccounts

All subaccounts for a wallet.

Response: Array of subaccounts with:
  - ID and label
  - Creation timestamp
  - Status

get_balance

Total balance across all subaccounts.

Response:
  - By collateral type (ETH, USDC, etc.)
  - Amounts and mark prices
  - Interest earned/owed
  - Margin contributions

get_positions

All open positions for a subaccount.

Parameters:
  - subaccount_id (required)
  - currency (optional): Filter
  - instrument_type (optional): erc20, option, perp

Response: Position details including:
  - Amount, entry price
  - Unrealized PnL (total and excluding fees)
  - Mark price vs index price
  - Greeks (for options)
  - Liquidation price
  - Leverage, margin requirements
  - Funding/interest accrual

get_collaterals

Collateral information for a subaccount.

Response:
  - Collateral amounts by asset
  - Mark prices and valuations
  - Interest rates (borrow/supply)
  - Margin contribution (initial and maintenance)

get_margin

Detailed margin metrics.

Response:
  - Maintenance margin required
  - Initial margin required
  - Current margin ratio
  - Available margin for new positions
  - Margin utilization status

Trading Tools

place_order

Place a new order for any instrument (options, perps, spot).

Parameters:
  - subaccount_id (required)
  - instrument_name (required): e.g., BTC-PERP, ETH-20250131-3000-C
  - side (required): buy or sell
  - amount (required): Order quantity
  - price (required for limit): Limit price
  - order_type (optional): limit (default) or market
  - reduce_only (optional): Can only reduce position (default false)
  - post_only (optional): Maker-only, no taker fills (default false)
  - label (optional): Custom order label

Response:
  - Order ID
  - Status (pending, filled, rejected)
  - Fill details if executed

cancel_order

Cancel a specific open order.

Parameters:
  - subaccount_id (required)
  - order_id (required): ID of order to cancel

cancel_all_orders

Cancel all open orders with optional filtering.

Parameters:
  - subaccount_id (required)
  - currency (optional): Only cancel this currency
  - instrument_name (optional): Only cancel this instrument

replace_order

Replace an order atomically (cancel + place in one operation).

Parameters:
  - subaccount_id (required)
  - order_id (required): Order to replace
  - amount (required): New amount
  - price (required): New price

get_open_orders

View all open orders for a subaccount.

Parameters:
  - subaccount_id (required)
  - currency (optional): Filter
  - instrument_name (optional): Filter

Response: Array of open orders with:
  - Order ID, status
  - Side, amount, price
  - Creation timestamp
  - Unfilled amount

get_orders_history

Complete order history (filled, cancelled, rejected).

Parameters:
  - subaccount_id (required)
  - currency (optional): Filter
  - instrument_name (optional): Filter
  - Pagination parameters

Account History Tools

get_my_trades

Personal trade history with P&L.

Parameters:
  - subaccount_id (required)
  - instrument_name (optional): Filter
  - currency (optional): Filter
  - Time range and pagination

Response:
  - Trade price, amount
  - Fees paid
  - Realized P&L
  - Maker/taker role
  - Timestamp, tx hash

get_funding_history

Funding payments paid and received.

Response:
  - Instrument (perpetual)
  - Funding payment amount and rate
  - P&L from funding
  - Timestamp

get_deposit_history

Deposit transactions.

Response:
  - Asset, amount
  - Transaction hash
  - Status (settled, reverted)
  - Timestamp

get_withdrawal_history

Withdrawal transactions.

Response:
  - Asset, amount
  - Transaction hash
  - Status
  - Timestamp

RFQ Tools

send_rfq

Request a quote from market makers.

Parameters:
  - subaccount_id (required)
  - instrument_name (required)
  - side (required): buy or sell
  - amount (required): Amount to quote

Response:
  - RFQ ID
  - Quotes received from different market makers
  - Best bid/ask from quotes

get_rfqs

View active RFQs and quotes.

Parameters:
  - subaccount_id (required)

Response:
  - Active RFQ requests
  - Quotes from market makers
  - Expiration times

execute_quote

Execute a market maker quote.

Parameters:
  - subaccount_id (required)
  - quote_id (required): Quote ID from RFQ

Response:
  - Execution confirmation
  - Final fill price and amount
  - Transaction hash

Risk Management Tools

get_liquidation_price

Get liquidation price for an open position.

Parameters:
  - subaccount_id (required)
  - instrument_name (required)

Response:
  - Liquidation price
  - Current mark price
  - Distance to liquidation
  - Position size

margin_watch

Accounts approaching liquidation.

Parameters:
  - wallet (optional): Wallet address

Response:
  - Subaccounts with low margin ratios
  - Current margin utilization
  - Recommended actions

Instrument Naming

Options Format

{CURRENCY}-{EXPIRY}-{STRIKE}-{TYPE}

Example: ETH-20250131-3000-C (ETH call, Jan 31 2025, $3000 strike)
Example: BTC-20250228-50000-P (BTC put, Feb 28 2025, $50000 strike)
Type: C (call) or P (put)

Perpetuals Format

{CURRENCY}-PERP

Example: BTC-PERP, ETH-PERP, SOL-PERP

Spot/ERC20 Format

{SYMBOL}

Example: USDC, ETH, WBTC

Authentication

Public Endpoints

No authentication required. Works without any credentials.

Private Endpoints

Require:

DERIVE_WALLET: Your Ethereum wallet address
DERIVE_PRIVATE_KEY: Optional, used for signing transactions

Uses wallet-based authentication:

X-LyraWallet: Your wallet address
X-LyraTimestamp: Current timestamp
X-LyraSignature: HMAC signature of timestamp

Rate Limits

Derive implements TPS (transactions per second) limits. Each account has:

WebSocket matching TPS (for trading orders)
WebSocket non-matching TPS (for RFQ, margin watch, etc.)
Per-instrument limits (options, perpetuals)
Global per-endpoint limits

Check your account's rate limits using get_account tool.

Usage Examples

Get Real-time BTC Perpetual Price

Ask Claude: "What's the current price of BTC-PERP?"

Claude will use: get_ticker(instrument_name="BTC-PERP")

View Your Positions

Ask Claude: "Show my open positions on subaccount 12345"

Claude will use: get_positions(subaccount_id=12345)

Place a Trade

Ask Claude: "Buy 0.5 BTC-PERP at $45000 on subaccount 12345"

Claude will use: place_order(
  subaccount_id=12345,
  instrument_name="BTC-PERP",
  side="buy",
  amount="0.5",
  price="45000"
)

Get Historical Trades

Ask Claude: "Show my trade history for ETH over the last 7 days"

Claude will use: get_my_trades(
  subaccount_id=12345,
  instrument_name="ETH-PERP",
  from_timestamp=<7-days-ago-ms>
)

Analyze Funding Rates

Ask Claude: "What are the funding rates for BTC and ETH perpetuals?"

Claude will use: get_funding_rate_history for both instruments

Performance & Rate Limiting

REST API: HTTP/REST (used by this MCP) - Most stable, less likely to hit rate limits
No WebSocket: Uses REST only (simpler, more compatible)
Pagination: Automatic pagination support for large result sets
Caching: Results not cached in MCP (fresh data on each call)

Rate Limiting Strategy

Use page_size=1000 for efficient historical data fetches
Batch related queries together
Avoid polling the same endpoint more than once per second
Check get_account for your specific TPS limits

Troubleshooting

"API Error" Responses

Invalid instrument name:

Use correct format: BTC-PERP, ETH-20250131-3000-C, etc.
Verify instrument is active using get_instruments

Authentication errors (private endpoints):

Ensure DERIVE_WALLET environment variable is set
Check wallet address is correct
For trading, ensure DERIVE_PRIVATE_KEY is set
Verify API key/credentials haven't expired

Rate limit exceeded:

Wait before making more requests
Check your TPS limits with get_account
Reduce page_size or request frequency

No positions/orders found:

Verify correct subaccount_id
Check subaccount has active trading
Use get_subaccounts to list available subaccounts

Network Issues

Verify network connectivity
Check if API is up: https://status.lyra.finance
Confirm correct environment (mainnet vs testnet)
Check DERIVE_ENVIRONMENT setting matches your API credentials

Additional Resources

License

MIT

Support

For issues with:

The MCP Server: File issues in this repository
Derive API: Check https://docs.derive.xyz or contact Derive support
Claude Integration: Check Claude documentation

Disclaimer

This is an unofficial MCP server for Derive. Use at your own risk. Always verify trades and transactions independently. The authors are not responsible for any financial losses resulting from use of this tool.

Risk Warning: Leverage trading involves significant risk of loss. Only trade with funds you can afford to lose.