内容
# 🏦 DeBank MCP 服务器
[](https://www.npmjs.com/package/@iqai/mcp-debank)
[](https://opensource.org/licenses/ISC)
## 📖 概述
DeBank MCP 服务器使 AI 代理能够与 [DeBank](https://debank.com) API 交互，以获取全面的区块链和 DeFi 数据。该服务器提供了访问链信息、协议分析、代币数据、用户投资组合、NFT 持仓、交易历史、Gas 价格和交易模拟功能。
通过实现模型上下文协议（MCP），该服务器允许大型语言模型（LLM）通过其上下文窗口直接发现区块链链、分析 DeFi 协议、跟踪用户投资组合和模拟交易，弥合了 AI 和去中心化金融数据之间的差距。
## ✨ 功能
* **多链支持**：访问 DeBank 索引的每个链（目前约 85 个，从 `/v1/chain/list` 实时获取），并具有人类可读名称的确定性解析（`"BSC"` → `"bsc"`）。
* **代码模式**：代理编写在 `isolated-vm` 沙盒中运行的 JavaScript，针对预认证的 DeBank 客户端 - 多步连接、投影和条件逻辑在一个工具调用中。
* **投资组合跟踪**：用户仓位、代币余额、NFT 和协议持仓，涵盖所有链。
* **DeFi 分析**：协议、流动性池和顶级持有者，附带 TVL 数据。
* **交易工具**：模拟交易、检查 Gas 和解码交易数据，然后再签名。
* **封装代币助手**：`"WETH"` / `"原生代币"` 关键字解析为链的封装原生合约地址。
* **本地文档搜索**：MiniSearch 索引涵盖整个 API 接口 + 食谱，嵌入到二进制文件中（无需网络）。
## 要求
- Node.js >= 22（由 `isolated-vm` 6.x 要求；较旧的 Node 版本无法运行 `execute` 沙盒）。
- 已发布的二进制文件的 shebang 已经传递 `--no-node-snapshot` 给 node。如果您直接调用 `node dist/index.js`（很少见），请自己传递 `--no-node-snapshot`：`node --no-node-snapshot dist/index.js`。
- `isolated-vm` 在 `optionalDependencies` 中声明，因此 `pnpm install` 将在没有预构建的插件或编译器工具链的平台上成功（例如某些 Alpine / ARM 主机）。服务器仍然启动，`search_docs` + 动态工具三件套仍然有效；只有 `execute` 将报告加载失败错误，直到您运行 `pnpm rebuild isolated-vm`。
## 📦 安装
### 🚀 使用 pnpm dlx（推荐）
无需全局安装即可使用此服务器：
```bash
pnpm dlx @iqai/mcp-debank
```
### 🔧 从源代码构建
```bash
git clone https://github.com/IQOfficial/mcp-debank.git
cd mcp-debank
pnpm install
pnpm run build
```
## ⚡ 使用 MCP 客户端运行
在您的 MCP 客户端设置中添加以下配置（例如 `claude_desktop_config.json`）。
### 📋 最小配置
```json
{
"mcpServers": {
"debank": {
"command": "pnpm",
"args": ["dlx", "@iqai/mcp-debank"],
"env": {
"DEBANK_API_KEY": "您的 DeBank API 密钥"
}
}
}
}
```
### ⚙️ 高级配置（使用 IQ Gateway）
```json
{
"mcpServers": {
"debank": {
"command": "pnpm",
"args": ["dlx", "@iqai/mcp-debank"],
"env": {
"IQ_GATEWAY_URL": "您的 IQ Gateway URL",
"IQ_GATEWAY_KEY": "您的 IQ Gateway 密钥"
}
}
}
}
```
## 🔐 配置（环境变量）
您必须提供 **以下任一项** `DEBANK_API_KEY` **或** `IQ_GATEWAY_URL` + `IQ_GATEWAY_KEY` 对。 如果两种配置方式均未配置，服务器启动将失败。
| 变量 | 必需 | 描述 | 默认值 |
| :--- | :--- | :--- | :--- |
| `DEBANK_API_KEY` | 其中一种路径 | 您的 DeBank API 密钥。在直接调用 `https://pro-openapi.debank.com` 时用作 `AccessKey` 头。 | - |
| `IQ_GATEWAY_URL` | 另一种路径 | IQ Gateway 基本 URL。当与 `IQ_GATEWAY_KEY` 一起设置时，所有 DeBank 调用都通过网关代理。 | - |
| `IQ_GATEWAY_KEY` | 另一种路径 | IQ Gateway API 密钥。作为 `x-api-key` 头发送到网关。 | - |
| `DEBANK_MCP_TOOLS` | 否 | 设置为 `dynamic` 以注册另外四个工具（`debank_resolve`、`list_endpoints`、`get_endpoint_schema`、`invoke_endpoint`），以及默认的 `execute` + `search_docs`。等效于在命令行上传递 `--tools=dynamic`。 | - |
| `LOG_LEVEL` | 否 | 可以是 `error`、`warn`、`info`、`debug`。`debug` 显示每次调用的 API 仪表盘（`[DeBank API] op=... ms=... ok=...`）和实体解析器跟踪 - 在诊断慢速端点时很有用，否则保持沉默。`info`（默认）保持日志安静：只有启动事件、真正警告和错误。 | `info` |
## 🖼️ 截图
MCP 调用 Claude Desktop 的真实会话。代理使用 `search_docs` 发现正确的方法，然后编写一个 `execute` 正文，链接多个 `debank.*` 调用并返回投影表。
> **注意：** 以下引用的图像文件位于 `docs/images/` 中。如果您刚刚克隆了存储库并且这些图像尚未渲染，请将 PNG 放入该文件夹中。
### 已注册并运行的本地 MCP 服务器
在将服务器连接到 `claude_desktop_config.json` 后，Claude Desktop 的 **设置 → 开发者 → 本地 MCP 服务器** 面板显示该条目，并带有绿色 **运行中** 状态徽章和确切的 `node --no-node-snapshot dist/index.js` 命令 + 参数。
### 投资组合查询端到端
> *"0x5853… 在以下协议中的余额是多少：eth、bsc、xdai？*
代理推理出正确的方法，编写一个 `execute` 正文，拉取所有三个链的协议余额并返回每个链的摘要表。
### `search_docs` 发现流程
当代理不确定要使用哪种方法时，它会首先调用 `search_docs`。MiniSearch 索引返回具有方法名称、描述和示例调用的排名匹配结果。
### 激活安全限制
当访客脚本超出每次执行调用预算或达到超时时，规范错误信封会显示清晰的消息，代理可以从中恢复（例如，重新尝试使用较小的范围）。
## 💡 使用示例
### 🔗 链数据
* "DeBank 支持哪些区块链？"
* "获取以太坊链的信息。"
* "显示 BSC（币安智能链）的详细信息。"
### 📊 协议分析
* "列出以太坊上的所有 DeFi 协议。"
* "获取 Uniswap 协议的信息。"
* "谁是 Aave 的顶级持有者？"
### 💰 代币数据
* "获取以太坊上 WETH 的代币信息。"
* "2024-01-01 时 USDT 的历史价格是多少？"
* "谁是该代币的顶级持有者？"
### 👛 投资组合跟踪
* "0x123... 钱包的总余额是多少？"
* "显示该地址在 Polygon 上持有的所有代币。"
* "列出该钱包的所有 DeFi 仓位。"
### 🖼️ NFT 持仓
* "该钱包在以太坊上拥有哪些 NFT？"
* "显示该地址的 NFT 审批情况。"
### ⛽ 交易工具
* "以太坊当前的 Gas 价格是多少？"
* "在提交此交易之前模拟它。"
* "解释此交易的作用。"
## 🧭 架构
```
┌────────────────────────────────────────────────────────────────────────────┐
│ Claude Desktop / Cursor / 任意 MCP 客户端 │
└─────────────────────────────────┬──────────────────────────────────────────┘
│ stdio (JSON-RPC)
▼
┌────────────────────────────────────────────────────────────────────────────┐
│ mcp-debank 服务器 │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ 默认工具 │ 动态工具（按需通过 --tools=...） │ │
│ │ ───────────────────── │ ──────────────────────────────────── │ │
│ │ execute │ debank_resolve │ │
│ │ search_docs │ list_endpoints │ │
│ │ │ get_endpoint_schema │ │
│ │ │ invoke_endpoint （带 jq_filter） │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │ │ │
│ ┌─────────▼──────────────┐ ┌──────────▼──────────────┐ │
│ │ isolated-vm 沙盒 │ │ 直接调度 │ │
│ │ • 128 MiB 容量 │ │ • zod 模式验证 │ │
│ │ • 30 秒时钟 │ │ • 5 秒 / 6 秒超时 │ │
│ │ • 作用域预算 + 插槽 │ │ • jq 投影 │ │
│ └────────────────────────┘ └─────────────────────────┘ │
│ └──────────────┬──────────────────┘ │
└───────────────────────────┼────────────────────────────────────────────────┘
│ HTTPS （AccessKey 或 IQ Gateway x-api-key）
▼
┌────────────────────────┐
│ DeBank 云 API │
└────────────────────────┘
```
### `execute` 工作原理（一次调用的生命周期）
```mermaid
sequenceDiagram
participant 代理
participant 工具 as execute（tool.ts）
participant 沙盒 as runInSandbox（sandbox.ts）
participant 访客 as 访客 JS<br/>(V8 隔离)
participant 桥 as installServiceCall<br/>(client.ts）
participant DeBank as DeBank API
代理->>工具：工具/调用 execute {code}
工具->>工具：createExecutionScope()<br/>(budget=100, concurrency=10)
工具->>沙盒：runInSandbox(code, installClient)
沙盒->>沙盒：new Isolate({memoryLimit:128MB})
沙盒->>桥：installDebankClient(ctx, scope)
桥-->>访客：install debank.user.*、debank.resolveChain、...
沙盒->>访客：script.run({timeout:30s})
访客->>桥：await debank.user.foo({...})
桥->>桥：tryReserveBudget<br/>acquireSlot<br/>safeParse(args)
桥->>DeBank：HTTPS（5秒超时 + 6秒 axios 超时）
DeBank-->>桥：JSON
桥-->>访客：envelope {ok:true, data}
访客-->>沙盒：return projected result
沙盒-->>工具：{ok, result, log_lines, err_lines}
工具->>工具：cancelScope() in finally
工具-->>代理：MCP 信封
```
关键见解：**只有投影返回值跨越 V8 边界**。代理编写 JavaScript，进行循环、连接和过滤；主机看到一个返回值，而不是 N 个中间响应。
## 代码模式
查询 DeBank 的首选方式是 `execute` + `search_docs` 对。这两个工具通过代理编写的 JavaScript 处理整个工作流程 — 发现、投影、多步骤组合。
### 默认工具界面
默认情况下，服务器注册恰好两个工具：
| 工具 | 目的 |
| :--- | :--- |
| `execute` | 在安全 `isolated-vm` 沙盒中运行代理编写的 JavaScript，针对完全配置的 DeBank 客户端。处理多步骤工作流程、循环、连接、条件逻辑和自定义投影。 |
| `search_docs` | 搜索嵌入的 MiniSearch 索引，涵盖所有 DeBank API 方法和食谱条目。 |
### `--tools=dynamic` 模式
使用 `--tools=dynamic`（或设置 `DEBANK_MCP_TOOLS=dynamic`）启动服务器，以注册另外四个工具：
| 工具 | 目的 |
| :--- | :--- |
| `debank_resolve` | 将人类可读的链名（"BSC"， "Polygon"）解析为 DeBank 链 ID。 |
| `list_endpoints` | 列出所有可用的端点限定名称。 |
| `get_endpoint_schema` | 检查特定端点的参数和响应形状。 |
| `invoke_endpoint` | 调用单个端点，附带可选的 `jq_filter` 进行主机侧投影。 |
**带有动态工具的 MCP 客户端配置：**
```json
{
"mcpServers": {
"debank": {
"command": "pnpm",
"args": ["dlx", "@iqai/mcp-debank", "--tools=dynamic"],
"env": {
"DEBANK_API_KEY": "您的 DeBank API 密钥"
}
}
}
}
```
或通过环境变量：
```json
{
"mcpServers": {
"debank": {
"command": "pnpm",
"args": ["dlx", "@iqai/mcp-debank"],
"env": {
"DEBANK_API_KEY": "您的 DeBank API 密钥",
"DEBANK_MCP_TOOLS": "dynamic"
}
}
}
}
```
### `execute` — 沙盒 JavaScript
在安全 `isolated-vm` 沙盒中运行任意 JavaScript。沙盒接收一个完全配置的 DeBank 客户端实例作为 `debank`。所有服务命名空间（`debank.chain`、`debank.protocol`、`debank.token`、`debank.user`、`debank.transaction`）均可用。池方法位于 `debank.protocol` 下；NFT 方法位于 `debank.user` 下。
**示例：**
```javascript
async function run(debank) {
return await debank.user.getUserTotalBalance({ id: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045" });
}
```
**预期响应：**
```json
{
"total_usd_value": 1234567.89,
"chain_list": [
{ "id": "eth", "usd_value": 800000.0 },
{ "id": "arb", "usd_value": 434567.89 }
]
}
```
### `search_docs` — 本地文档搜索
搜索嵌入的 MiniSearch 索引，涵盖所有 DeBank API 方法和食谱条目。
**示例查询：** `用户总余额`
**修剪结果：**
```json
{
"results": [
{
"kind": "method",
"qualified": "debank.user.getUserTotalBalance",
"name": "debank_get_user_total_balance",
"description": "检索用户的跨所有支持链的总净资产。计算并返回包括代币和协议仓位在内的总美元价值。提供用户的 DeFi 投资组合的完整快照。",
"params": {
"type": "object",
"properties": {
"id": { "type": "string", "description": "用户的钱包地址。"}
},
"required": ["id"]
},
"exampleCall": "await debank.user.getUserTotalBalance({id: '0x...'})"
}
]
}
```
### 安全限制
`execute` 沙盒强制执行五个边界。默认设置针对合法的 Promise.all 风格工作进行了调整；两个预算旋钮可为测试和收紧而覆盖。
| 限制 | 默认值 | 覆盖方式 | 行为（触发时） |
| :--- | :--- | :--- | :--- |
| 隔离内存 | 128 MiB | 硬编码 | 隔离被终止；错误表现为 `"Script execution timed out"`（V8 在某些路径上将 OOM 与超时混淆） |
| 脚本时钟 | 30 秒 | `DEBANK_MCP_SANDBOX_DEADLINE_MS`（仅限测试） | 返回 `"Execute timed out after 30s. No call to settle, or guest stuck in a non-yielding loop."` |
| 每次调用 | 100 | `DEBANK_MCP_EXECUTE_BUDGET` | 之后的访客调用返回 `"Execute call budget exceeded (100 calls per invocation): <method>"` |
| 并发调用 | 10 | `DEBANK_MCP_EXECUTE_CONCURRENCY` | 调用在一个信号量上排队；不会报错，只是背压 |
| 单次调用上游 | 5 秒超时 + 6 秒 axios | 硬编码 | 返回 `"DeBank call timed out after 5s: <method>"` |
沙盒还会在提交时阻止源级标识符 `process.`、`require(`、`import(` 和 `eval(`。这些不是安全边界（隔离是），而是从快速失败的清晰消息中进行防御性检查。
在每次访客调用时都会强制执行模式验证：参数会根据方法的已发布模式进行 zod 解析，然后再发送到上游服务。访客调用 `debank.protocol.getTopHoldersOfProtocol({id:"uniswap", limit:999999})` 将被拒绝，并显示 `"Invalid arguments for debank.protocol.getTopHoldersOfProtocol: Too big: expected number to be <=100"` — 元数据中的边界是真实的，而不是建议性的。
### 带有 `jq_filter` 的 `invoke_endpoint`
`invoke_endpoint`（在 `--tools=dynamic` 模式下）接受一个可选的 `jq_filter`，该过滤器在响应 **返回给代理之前** 投影 - 减少响应大小并跳过客户端解析。
```json
{
"name": "debank.user.getUserTotalBalance",
"params": { "id": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045" },
"jq_filter": ".total_usd_value"
}
```
返回标量值：
```json
1234567.89
```
常见模式：
| 目标 | jq 过滤器 |
| :--- | :--- |
| 投影一个字段 | `.total_usd_value` |
| 从每个项目中选取 | `.[] \| {symbol, usd_value}` |
| 过滤然后投影 | `[.[] \| select(.usd_value > 100) \| .symbol]` |
| 聚合 | `[.[] \| .usd_value] \| add` |
过滤器通过 [jqts](https://github.com/mwri/jqts)（纯 JS，无需原生 `jq` 二进制文件）在每个平台上运行。
### 错误信封
每个工具都返回 MCP 标准 `{ content: [{ type, text }], isError }` 信封。`text` 是包含以下内容的 JSON：
| 形状 | 您看到它的情况 |
| :--- | :--- |
| `{"ok": true, "result": ..., "log_lines": [], "err_lines": []}` | `execute` 成功；`result` 是 `run(debank)` 返回的内容 |
| `{"ok": false, "error": "...", "log_lines": [], "err_lines": [...]}` | `execute` 失败；规范消息在上面的安全限制中列出 |
| `{"results": [...]}` | `search_docs` 命中 |
| `{"resolved": "<id>"}` 或 `{"resolved": null, "error": "..."}` | `debank_resolve` |
| `{"endpoints": [...]}` | `list_endpoints` |
| `{"qualified", "description", "params", "response", "exampleCall"}` | `get_endpoint_schema` |
| 原始方法 JSON（或 jq 投影） | `invoke_endpoint` 成功 |
| `{"error": "..."}` | `invoke_endpoint` 失败（规范超时消息与 `execute` 的超时消息匹配） |
来自上游 API（身份验证失败、链 ID 不支持、5xx）的错误会直接传回，附带 DeBank 的错误消息 - 不会重写。
错误不一定来源于上游 API 的错误（身份验证失败，链 ID 不支持，5xx 错误）会直接返回 DeBank 的错误信息 - 不会重写。
### 从早期版本迁移
30个端点特定的`debank_*`工具（此前位于`--legacy-tools`后）已被**移除**。对于多步骤工作流，请使用`execute`，或使用`--tools=dynamic`开始进行每个端点的调度三元组：
- **`list_endpoints`** — 发现可用的端点及其限定名称。
- **`get_endpoint_schema`** — 检查特定端点的参数和响应形状。
- **`invoke_endpoint`** — 调用单个端点，并使用可选的`jq_filter`进行主机侧投影。
`OPENROUTER_API_KEY`、`LLM_MODEL`、`GOOGLE_GENERATIVE_AI_API_KEY`、`--legacy-tools`和`DEBANK_MCP_LEGACY`标志/环境变量不再被识别。
## 👨💻 开发
### 🏗️ 构建项目
```bash
pnpm run build
```
### 👁️ 开发模式（监视）
```bash
pnpm run watch
```
### ✅ 校验和格式化
```bash
pnpm run lint
pnpm run format
```
### 📁 项目结构
```
src/
├── index.ts # 服务器入口点（FastMCP 注册）
├── env.ts # 环境验证（dotenv + zod）
├── config.ts # 缓存 TTL
├── types.ts # 共享 TypeScript 类型
├── services/ # DeBank API 客户端（每个域一个 *.service.ts）
├── lib/
│ ├── entity-resolver.ts # resolveChain / resolveChains / resolveWrappedToken
│ └── utils/ # 日志记录器、错误处理程序
├── mcp/
│ ├── tools.ts # debank_resolve（动态模式）
│ ├── execute/ # 代码模式：沙箱 + 客户端 + 作用域 + 工具
│ ├── search-docs/ # MiniSearch 索引 + 工具 + 食谱
│ ├── endpoints/ # list_endpoints / get_endpoint_schema / invoke_endpoint
│ ├── instructions/ # instructions.md → instructions.generated.ts
│ └── legacy/ # 工具元数据 + 响应模式（由 execute & 端点工具共享）
└── enums/chains.ts # 捆绑的链目录（当 DeBank /v1/chain/list 失败时的备用）
scripts/
├── build-docs-index.ts # 预构建：工具元数据 + 食谱 → embedded-index.ts
└── build-instructions.ts # 预构建：instructions.md → instructions.generated.ts
tests/integration/ # 端到端测试（启动构建的服务器）
```
## 📚 资源
* [DeBank API 文档](https://docs.cloud.debank.com/)
* [模型上下文协议（MCP）](https://modelcontextprotocol.io)
* [DeBank 平台](https://debank.com)
## ⚠️ 免责声明
本项目是一个非官方工具，与 DeBank 没有直接关联。它与区块链和 DeFi 数据交互。用户应谨慎行事，并独立验证所有数据。DeFi 交互涉及风险。
## 📄 许可证
[ISC](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器