内容
# Derive MCP 交易服务器
一个MCP（模型上下文协议）服务器，暴露 [Derive.xyz](https://derive.xyz) 的交易能力，作为像 Claude 这样的AI代理的工具。
## ⚠️ 重要警告
### 真实资金
该服务器下达 **真实交易，使用真实加密货币**。请自担风险：
- 从小额开始
- 在使用较大仓位之前进行彻底测试
- 永远不要投资超过你能承受损失的金额
### 地理限制
**Derive.xyz 可能会阻止某些国家的访问，包括加拿大。** 如果您收到 403 禁止错误，您可能需要使用连接到允许区域的VPN。
## 设置
### 1. 安装依赖项
```bash
cd derive-mcp-trader
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### 2. 生成会话密钥
```bash
python generate_session_key.py
```
这将打印一个私钥和地址。 **保存私钥** — 您将在步骤 4 中需要它。
### 3. 在 Derive 上注册会话密钥
1. 前往 [app.derive.xyz](https://app.derive.xyz)
2. 导航到：**首页 → 开发者 → 会话密钥**
3. 将步骤 2 中的 **地址** 注册为新的会话密钥
4. 在同一个开发者页面，记录以下值：
- **`DERIVE_WALLET_ADDRESS`** — 在 **钱包** 下显示的地址（这是您的 Derive 智能合约钱包，**不是** 签名者/EOA 地址）
- **`DERIVE_SUBACCOUNT_ID`** — 您的子账户 ID
### 4. 保存凭证
```bash
python credentials.py
```
这将通过隐藏输入（不会记录在 shell 历史记录中）提示您输入会话密钥、钱包地址和子账户 ID，并将它们保存到具有 `600` 权限的 `.env` 文件中。
### 5. 运行 MCP 服务器
```bash
source .venv/bin/activate
python server.py
```
## Claude 桌面配置
将以下内容添加到您的 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"derive-trader": {
"command": "/path/to/derive-mcp-trader/.venv/bin/python",
"args": ["/path/to/derive-mcp-trader/server.py"]
}
}
}
```
将 `/path/to/derive-mcp-trader` 替换为该目录的实际路径。
## 可用的 MCP 工具
### 市场数据（公开，无身份验证）
| 工具 | 描述 |
|---|---|
| `get_instruments` | 按货币和类型（期权/永续/现货）列出可用工具 |
| `get_ticker` | 获取工具的价格、成交量和市场数据 |
| `get_orderbook` | 获取工具的买卖报价 |
### 账户（身份验证）
| 工具 | 描述 |
|---|---|
| `get_positions` | 显示所有开仓位的盈亏 |
| `get_open_orders` | 显示所有待处理订单 |
| `get_balance` | 显示每种资产的抵押品和余额 |
### 交易（身份验证）
| 工具 | 描述 |
|---|---|
| `place_order` | 下达买入或卖出订单（限价/市价） |
| `cancel_order` | 按 ID 取消特定订单 |
| `cancel_all_orders` | 取消所有开仓订单（可选，仅限一种工具） |
## 项目结构
```
derive-mcp-trader/
├── server.py # MCP 服务器入口点
├── derive_client.py # API 客户端（身份验证、签名、REST 调用）
├── credentials.py # 独立凭证设置（写入 .env）
├── generate_session_key.py # 生成会话密钥的以太坊密钥对
├── requirements.txt # Python 依赖项
├── README.md # 本文件
└── .env # 凭证（自动创建，gitignored）
```
## 安全
- **会话密钥**：使用会话密钥而不是您的主钱包私钥
- **隐藏输入**：`credentials.py` 使用 `getpass` — 不会在 shell 历史记录中记录任何内容
- **权限**：`.env` 创建时具有 600 权限（仅所有者）
- **撤销**：您可以通过 Derive UI 随时撤销会话密钥
- **从不提交**：`.env` 永远不应提交到版本控制
## 故障排除
### 403 禁止错误
Derive.xyz 可能会阻止某些国家的访问。使用连接到允许区域的VPN。
### 身份验证失败
- 验证您的会话密钥是否正确且未过期
- 检查 Derive 钱包地址是否与您的账户匹配
- 确保会话密钥已为您的子账户注册
### 缺少凭证错误
运行 `python credentials.py` 以设置或重新输入您的凭证。
### 协议常量
如果 `place_order` 失败并出现签名错误，则可能需要从 [docs.derive.xyz/reference/protocol-constants](https://docs.derive.xyz/reference/protocol-constants) 更新 `derive_client.py` 中的协议常量。
## 资源
- [Derive 文档](https://docs.derive.xyz)
- [API 参考](https://docs.derive.xyz/reference)
- [derive_action_signing PyPI](https://pypi.org/project/derive-action-signing/)
- [协议常量](https://docs.derive.xyz/reference/protocol-constants)
- [MCP 规范](https://modelcontextprotocol.io)
