使用说明
Derive MCP Trading Server
An MCP (Model Context Protocol) server that exposes Derive.xyz trading capabilities as tools for AI agents like Claude.
⚠️ Important Warnings
Real Money
This server places real trades with real cryptocurrency. Use at your own risk:
- Start with small amounts
- Test thoroughly before using larger positions
- Never invest more than you can afford to lose
Geo-Restrictions
Derive.xyz may block access from certain countries, including Canada. If you receive 403 Forbidden errors, you may need to use a VPN connected to an allowed region.
Setup
1. Install Dependencies
cd derive-mcp-trader
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
2. Generate a Session Key
python generate_session_key.py
This prints a private key and address. Save the private key — you'll need it in step 4.
3. Register the Session Key on Derive
- Go to app.derive.xyz
- Navigate to: Home → Developers → Session Keys
- Register the address from step 2 as a new session key
- On the same Developers page, note the following values:
DERIVE_WALLET_ADDRESS— the address shown under "Wallet" (this is your Derive smart contract wallet, not the Signer/EOA address)DERIVE_SUBACCOUNT_ID— your subaccount ID
4. Save Credentials
python credentials.py
This prompts for your session key, wallet address, and subaccount ID via hidden input (not logged in shell history) and saves them to a .env file with 600 permissions.
5. Run the MCP Server
source .venv/bin/activate
python server.py
Claude Desktop Configuration
Add to your claude_desktop_config.json:
{
"mcpServers": {
"derive-trader": {
"command": "/path/to/derive-mcp-trader/.venv/bin/python",
"args": ["/path/to/derive-mcp-trader/server.py"]
}
}
}
Replace /path/to/derive-mcp-trader with the actual path to this directory.
Available MCP Tools
Market Data (public, no auth)
| Tool | Description |
|---|---|
get_instruments |
List available instruments by currency and type (option/perp/spot) |
get_ticker |
Get price, volume, and market data for an instrument |
get_orderbook |
Get bids and asks for an instrument |
Account (authenticated)
| Tool | Description |
|---|---|
get_positions |
Show all open positions with P&L |
get_open_orders |
Show all pending orders |
get_balance |
Show collateral and balance per asset |
Trading (authenticated)
| Tool | Description |
|---|---|
place_order |
Place a buy or sell order (limit/market) |
cancel_order |
Cancel a specific order by ID |
cancel_all_orders |
Cancel all open orders (optionally for one instrument) |
Project Structure
derive-mcp-trader/
├── server.py # MCP server entry point
├── derive_client.py # API client (auth, signing, REST calls)
├── credentials.py # Standalone credential setup (writes .env)
├── generate_session_key.py # Generate Ethereum keypair for session key
├── requirements.txt # Python dependencies
├── README.md # This file
└── .env # Credentials (auto-created, gitignored)
Security
- Session Keys: Use session keys instead of your main wallet private key
- Hidden Input:
credentials.pyusesgetpass— nothing logged in shell history - Permissions:
.envis created with 600 permissions (owner only) - Revocation: You can revoke session keys anytime via the Derive UI
- Never commit:
.envshould never be committed to version control
Troubleshooting
403 Forbidden Error
Derive.xyz may block access from certain countries. Use a VPN connected to an allowed region.
Authentication Failed
- Verify your session key is correct and hasn't expired
- Check that the Derive Wallet address matches your account
- Ensure the session key is registered for your subaccount
Missing Credentials Error
Run python credentials.py to set up or re-enter your credentials.
Protocol Constants
If place_order fails with signing errors, the protocol constants in derive_client.py may need updating from docs.derive.xyz/reference/protocol-constants.
