使用说明

🏦 DeBank MCP服务器

📖 概述

DeBank MCP服务器使AI代理能够与德班克 API，用于全面的区块链和DeFi数据访问。该服务器提供访问链信息、协议分析、令牌数据、用户投资组合、NFT持有、交易历史、天然气价格和交易模拟功能的工具。

通过实施模型上下文协议（MCP），该服务器允许大型语言模型（LLM）发现区块链链、分析DeFi协议、跟踪用户投资组合，并直接通过其上下文窗口模拟交易，从而弥合了人工智能和去中心化金融数据之间的差距。

✨ 特性

多链支持：访问每个链的DeBank索引（目前约为85，从实时获取 /v1/chain/list)，具有人类可读名称的确定性分辨率("BSC" → "bsc").
代码模式：代理编写在 isolated-vm 沙盒针对预先经过身份验证的DeBank客户端——在一个工具调用中包含多步连接、投影和条件逻辑。
投资组合跟踪：所有链上的用户头寸、代币余额、NFT和协议持有量。
DeFi 分析：协议、流动性池和拥有TVL数据的顶级持有者。
交易工具：在签名之前模拟交易、检查气体和解码交易数据。
包装令牌助手: "WETH" / "native token" 关键字解析为链的包装本地合约地址。
本地文档搜索：整个API表面+食谱的MiniSearch索引，嵌入二进制（无网络）。

需求

Node.js>=22（需要 isolated-vm 6.x；较旧的节点版本无法运行 execute 沙盒）。
已发布的二进制文件的shebang已经通过 --no-node-snapshot 到节点。如果你调用 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（推荐）

要使用此服务器而不全局安装，请执行以下操作：

pnpm dlx @iqai/mcp-debank

🔧 从源代码构建

git clone https://github.com/IQOfficial/mcp-debank.git
cd mcp-debank
pnpm install
pnpm run build

⚡ 使用MCP客户端运行

将以下配置添加到MCP客户端设置中（例如。， claude_desktop_config.json).

📋 最小配置

{
  "mcpServers": {
    "debank": {
      "command": "pnpm",
      "args": ["dlx", "@iqai/mcp-debank"],
      "env": {
        "DEBANK_API_KEY": "your_debank_api_key_here"
      }
    }
  }
}

⚙️ 高级配置（带IQ网关）

{
  "mcpServers": {
    "debank": {
      "command": "pnpm",
      "args": ["dlx", "@iqai/mcp-debank"],
      "env": {
        "IQ_GATEWAY_URL": "your_iq_gateway_url",
        "IQ_GATEWAY_KEY": "your_iq_gateway_key"
      }
    }
  }
}

🔐 配置（环境变量）

您必须提供要么 DEBANK_API_KEY 或这 IQ_GATEWAY_URL + IQ_GATEWAY_KEY 一对。如果两个路径都未配置，则服务器启动失败。

变量	必填	描述	默认值
`DEBANK_API_KEY`	一个路径	您的DeBank API密钥。用作 `AccessKey` 直接呼叫的标题 `https://pro-openapi.debank.com`.	-
`IQ_GATEWAY_URL`	其他路径	IQ网关基本URL。与一起设置时 `IQ_GATEWAY_KEY`，所有DeBank呼叫都通过网关代理。	-
`IQ_GATEWAY_KEY`	其他路径	IQ网关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。代理人使用 search_docs 为了找到正确的方法，然后编写一个 execute 连接多个物体的身体 debank.* 调用并返回一个投影表。

注：下面引用的图像文件实时存在 docs/images/。如果您刚刚克隆了仓库，但这些仓库尚未渲染，请将PNG放入该文件夹。

本地MCP服务器已注册并正在运行

将服务器连接到 claude_desktop_config.json，克劳德桌面 设置→ 开发者→ 本地MCP服务器 面板以绿色显示条目跑步身份徽章和确切信息 node --no-node-snapshot dist/index.js 命令+参数正在生成。

端到端的投资组合查询

“以下协议中0x5853的余额是多少：eth、bsc、xdai？”

代理对正确的方法进行推理，编写一个 execute 该主体并行提取所有三条链的协议平衡，并返回每条链的汇总表。

`search_docs` 发现流

当代理不确定使用哪种方法时，它会调用 search_docs 第一。MiniSearch索引返回带有方法名称、描述和示例调用的排名匹配。

行动中的安全限制

当客户脚本超过每次执行的调用预算或超时时，规范错误信封会显示一条明确的消息，代理可以从中恢复（例如，在较小的范围内重试）。

💡 使用示例

🔗 链数据

“德银支持哪些区块链？”
“获取有关以太坊链的信息。”
“显示BSC（币安智能链）的详细信息。”

📊 协议分析

“列出以太坊上的所有DeFi协议。”
“获取有关Uniswap协议的信息。”
“谁是Aave的最高持有者？”

💰 令牌数据

“在以太坊上获取WETH的代币信息。”
“2024年1月1日USDT的历史价格是多少？”
“谁是这个代币的最大持有者？”

👛 投资组合跟踪

“钱包0x123的总余额是多少……？”
“在Polygon上显示此地址持有的所有令牌。”
“列出此钱包的所有DeFi头寸。”

🖼️ NFT控股

“这个钱包在以太坊上拥有什么NFT？”
“显示此地址的NFT批准。”

⛽ 交易工具

“以太坊目前的天然气价格是多少？”
“在我提交之前模拟此交易。”
“解释一下这笔交易的作用。”

🧭 建筑

┌────────────────────────────────────────────────────────────────────────────┐
│  Claude Desktop / Cursor / any MCP client                                  │
└─────────────────────────────────┬──────────────────────────────────────────┘
                                  │  stdio (JSON-RPC)
                                  ▼
┌────────────────────────────────────────────────────────────────────────────┐
│  mcp-debank server                                                         │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │  Default tools           │  Dynamic tools (opt-in via --tools=...)   │  │
│  │  ─────────────────────   │  ────────────────────────────────────     │  │
│  │  execute                 │  debank_resolve                           │  │
│  │  search_docs             │  list_endpoints                           │  │
│  │                          │  get_endpoint_schema                      │  │
│  │                          │  invoke_endpoint  (with jq_filter)        │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│            │                              │                                │
│  ┌─────────▼──────────────┐    ┌──────────▼──────────────┐                 │
│  │ isolated-vm sandbox    │    │ direct dispatch         │                 │
│  │ • 128 MiB cap          │    │ • zod schema validate   │                 │
│  │ • 30 s wall clock      │    │ • 5 s / 6 s timeouts    │                 │
│  │ • scope budget+slots   │    │ • jq projection         │                 │
│  └────────────────────────┘    └─────────────────────────┘                 │
│            └──────────────┬──────────────────┘                             │
└───────────────────────────┼────────────────────────────────────────────────┘
                            │  HTTPS  (AccessKey or IQ Gateway x-api-key)
                            ▼
                ┌────────────────────────┐
                │  DeBank Cloud API      │
                └────────────────────────┘

如何 `execute` 作品（一次通话的生命周期）

sequenceDiagram
  participant Agent
  participant Tool as execute (tool.ts)
  participant Sandbox as runInSandbox (sandbox.ts)
  participant Guest as Guest JS<br/>(V8 isolate)
  participant Bridge as installServiceCall<br/>(client.ts)
  participant DeBank as DeBank API

  Agent->>Tool: tools/call execute {code}
  Tool->>Tool: createExecutionScope()<br/>(budget=100, concurrency=10)
  Tool->>Sandbox: runInSandbox(code, installClient)
  Sandbox->>Sandbox: new Isolate({memoryLimit:128MB})
  Sandbox->>Bridge: installDebankClient(ctx, scope)
  Bridge-->>Guest: install debank.user.*, debank.resolveChain, ...
  Sandbox->>Guest: script.run({timeout:30s})
  Guest->>Bridge: await debank.user.foo({...})
  Bridge->>Bridge: tryReserveBudget<br/>acquireSlot<br/>safeParse(args)
  Bridge->>DeBank: HTTPS (5s abort + 6s axios timeout)
  DeBank-->>Bridge: JSON
  Bridge-->>Guest: envelope {ok:true, data}
  Guest-->>Sandbox: return projected result
  Sandbox-->>Tool: {ok, result, log_lines, err_lines}
  Tool->>Tool: cancelScope() in finally
  Tool-->>Agent: MCP envelope

关键见解： 只有投影返回值穿过V8边界代理编写循环、连接和过滤的JS；主机看到一个返回值，而不是N个中间响应。

代码模式

从AI代理查询DeBank的首选方式是 execute + search_docs 一对。这两个工具通过代理编写的JavaScript处理完整的工作流程——发现、投影、多步骤组合。

默认刀具表面

默认情况下，服务器只注册两个工具：

工具	目的
`execute`	在安全的环境中运行代理编写的JavaScript `isolated-vm` 在完全配置的DeBank客户端上使用沙盒。处理多步骤工作流、循环、连接、条件逻辑和自定义投影。
`search_docs`	在所有DeBank API方法和食谱条目上搜索嵌入式MiniSearch索引。

`--tools=dynamic` 模式

使用启动服务器 --tools=dynamic （或设置 DEBANK_MCP_TOOLS=dynamic)注册四个附加工具：

工具	目的
`debank_resolve`	将人类可读的链名（“BSC”、“Polygon”）解析为DeBank链ID
`list_endpoints`	列出所有可用的端点限定名称。
`get_endpoint_schema`	检查特定端点的参数和响应形状。
`invoke_endpoint`	使用可选参数调用单个端点 `jq_filter` 用于主机侧投影。

使用动态工具配置MCP客户端：

{
  "mcpServers": {
    "debank": {
      "command": "pnpm",
      "args": ["dlx", "@iqai/mcp-debank", "--tools=dynamic"],
      "env": {
        "DEBANK_API_KEY": "your_debank_api_key_here"
      }
    }
  }
}

或者通过环境变量：

{
  "mcpServers": {
    "debank": {
      "command": "pnpm",
      "args": ["dlx", "@iqai/mcp-debank"],
      "env": {
        "DEBANK_API_KEY": "your_debank_api_key_here",
        "DEBANK_MCP_TOOLS": "dynamic"
      }
    }
  }
}

`execute` --沙盒JavaScript

在安全环境中运行任意JavaScript isolated-vm 沙箱。沙盒接收一个完全配置的DeBank客户端实例，作为 debank.所有服务命名空间(debank.chain, debank.protocol, debank.token, debank.user, debank.transaction)可用。池方法如下 debank.protocolNFT方法位于 debank.user.

例子：

async function run(debank) {
  return await debank.user.getUserTotalBalance({ id: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045" });
}

预期响应：

{
  "total_usd_value": 1234567.89,
  "chain_list": [
    { "id": "eth", "usd_value": 800000.0 },
    { "id": "arb", "usd_value": 434567.89 }
  ]
}

`search_docs` --本地文档搜索

在所有DeBank API方法和食谱条目上搜索嵌入式MiniSearch索引。

查询示例： user total balance

修剪结果：

{
  "results": [
    {
      "kind": "method",
      "qualified": "debank.user.getUserTotalBalance",
      "name": "debank_get_user_total_balance",
      "description": "Retrieve a user's total net assets across all supported chains. Calculates and returns the total USD value of assets including both tokens and protocol positions. Provides a complete snapshot of the user's DeFi portfolio.",
      "params": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "The user's wallet address." }
        },
        "required": ["id"]
      },
      "exampleCall": "await debank.user.getUserTotalBalance({id: '0x...'})"
    }
  ]
}

安全限制

这 execute 沙盒强制执行六个边界。默认值已针对合法的Promise.all-style工作进行了调整；预算旋钮可用于测试和紧缩。

限制	默认	覆盖	命中时的行为
隔离内存	128MiB	硬编码	隔离终止；误差曲面如 `"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."`
通话次数 `execute`	100	`DEBANK_MCP_EXECUTE_BUDGET`	后续客人来电返回 `"Execute call budget exceeded (100 calls per invocation): <method>"`
同时通话	10	`DEBANK_MCP_EXECUTE_CONCURRENCY`	调用信号队列；没有错误，只是背压
上游每次调用	5秒中止+6s轴	硬编码	返回 `"DeBank call timed out after 5s: <method>"`
结果大小	200000个字符（约50k个令牌）	`DEBANK_MCP_EXECUTE_RESULT_BUDGET_CHARS`	散装 `result` 被截断（数组保留前N个；对象修剪其最大的数组；字符串保留前缀）和 `_truncated: { shown, total, reason, hint }` 信号已附加。信封元数据(`ok` / `error` / `log_lines` / `err_lines`)始终保持不变，因此消费模型会获得一个有界的、可操作的有效载荷，而不是在whale钱包查询时溢出其上下文窗口。

沙盒还会阻止源代码级标识符 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" --元数据中的界限是真实的，而不是建议性的。

`invoke_endpoint` 随着 `jq_filter`

invoke_endpoint （in --tools=dynamic 模式）接受可选 jq_filter 预测反应 在它回到代理之前 --减少响应大小并跳过客户端解析。

{
  "name": "debank.user.getUserTotalBalance",
  "params": { "id": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045" },
  "jq_filter": ".total_usd_value"
}

仅返回标量：

1234567.89

常见模式：

目标	jq过滤器
项目一现场	`.total_usd_value`
从每个项目中挑选	`.[] \| {symbol, usd_value}`
过滤然后投影	`[.[] \| select(.usd_value > 100) \| .symbol]`
聚合	`[.[] \| .usd_value] \| add`

过滤器贯穿间隙可调式球团圆辊筛（纯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`s

源于上游API的错误（auth failure，ChainID-not-supported，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 标志/env变量不再被识别。

👨‍💻 发展

🏗️ 生成项目

pnpm run build

👁️ 开发模式（观看）

pnpm run watch

✅ 装订和格式化

pnpm run lint
pnpm run format

📁 项目结构

src/
├── index.ts                     # Server entry point (FastMCP registration)
├── env.ts                       # Env validation (dotenv + zod)
├── config.ts                    # Cache TTLs
├── types.ts                     # Shared TypeScript types
├── services/                    # DeBank API client (one *.service.ts per domain)
├── lib/
│   ├── entity-resolver.ts       # resolveChain / resolveChains / resolveWrappedToken
│   └── utils/                   # logger, error-handler
├── mcp/
│   ├── tools.ts                 # debank_resolve (dynamic mode)
│   ├── execute/                 # Code Mode: sandbox + client + scope + tool
│   ├── search-docs/             # MiniSearch index + tool + cookbook recipes
│   ├── endpoints/               # list_endpoints / get_endpoint_schema / invoke_endpoint
│   ├── instructions/            # instructions.md → instructions.generated.ts
│   └── legacy/                  # tool-metadata + response-schemas (shared by execute & endpoint tools)
└── enums/chains.ts              # Bundled chain catalog (fallback when DeBank /v1/chain/list fails)

scripts/
├── build-docs-index.ts          # Pre-build: tool-metadata + cookbook → embedded-index.ts
└── build-instructions.ts        # Pre-build: instructions.md → instructions.generated.ts

tests/integration/               # End-to-end tests (spawn the built server)

📚 资源

⚠️ 免责声明

该项目是一个非官方工具，与DeBank没有直接联系。它与区块链和DeFi数据交互。用户应谨慎行事，独立验证所有数据。DeFi交互涉及风险。

📄 许可证

国际学生中心