Skip to main content
Glama

zapper-mcp

一个将 Zapper DeFi 投资组合 API 作为精心设计的工具界面公开给 LLM 客户端的 MCP 服务器。将其连接到 Claude Desktop 或任何兼容 MCP 的主机,即可针对任何钱包提出自然语言问题——“这个钱包价值多少?”、“它有任何 Aave 头寸吗?”、“向我展示 Base 链上的顶级持仓。”

构建于 21 天 AI 工程冲刺的第 9 天。第 10 天将此服务器接入 Mastra 代理。


工具界面

每个原语的设计原理都在 DESIGN.md 中。简而言之:

原语

名称

放置原因

工具

get_portfolio

模型调用,每个地址动态生成,返回完整的代币 + DeFi 分解

工具

get_token_balances

针对现货代币问题的专用工具;避免在模型仅需代币持仓时解析整个投资组合

工具

get_app_positions

针对 DeFi 问题的专用工具;与 get_portfolio 分离,以便模型能够表达精确意图并接收聚焦的模式

资源

zapper://supported-networks

静态网络列表——主机在提示词组装时将其作为环境上下文注入,以便模型无需消耗工具调用次数即可获知有效的网络名称

提示词

analyze-wallet

用户调用的工作流,预先启动一个包含分析师角色、工具清单和钱包地址的多轮投资组合分析对话

为什么不使用一个大的 get_everything 工具? 合并工具会迫使模型在每次提问时接收并解析一个大型的混合模式响应,即使是针对性的问题。工具边界是范围的声明——正确的工具返回推理步骤所需的精确内容。

为什么 API 密钥在服务器配置中,而不是作为工具参数? 凭据属于主机层(在进程启动时注入的环境变量),而不是 MCP 协议。如果 api_key 是工具参数,它将流经 LLM 的推理过程并出现在对话历史中。对于多租户部署,正确的机制是传输层身份验证(通过 Streamable HTTP 的 Bearer 令牌)或每用户 OAuth——两者均超出此处范围。参见 已知限制。


Related MCP server: Ankr API MCP Server

要求


安装

git clone https://github.com/mehdi-loup/zapper-mcp
cd zapper-mcp
pnpm install
pnpm build

配置

将 .env.example 复制到 .env 并添加您的密钥:

cp .env.example .env
# edit .env and set ZAPPER_API_KEY=your_key_here

如果缺少 ZAPPER_API_KEY,服务器会在启动时快速失败——您会立即看到错误,而不是在第一次工具调用时才看到。


运行

独立冒烟测试(确认无需 Claude Desktop 即可正常工作):

ZAPPER_API_KEY=your_key pnpm client

输出:列出工具/资源/提示词,然后针对 vitalik.eth 调用每个工具。

直接启动服务器:

ZAPPER_API_KEY=your_key pnpm start

Claude Desktop 连接

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "zapper-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/zapper-mcp/build/server.js"],
      "env": {
        "ZAPPER_API_KEY": "your_key_here"
      }
    }
  }
}

重启 Claude Desktop。三个工具、zapper://supported-networks 资源和 analyze-wallet 提示词将可用。

日志(如果服务器加载失败):

~/Library/Logs/Claude/mcp-server-zapper-mcp.log

Mastra 集成(第 10 天)

要通过 Mastra 的 MCP 客户端将此服务器接入 Mastra 代理:

  1. 启动服务器:node /path/to/build/server.js

  2. 使用 stdio 传输配置 Mastra MCP 客户端,服务器名称为 zapper-mcp

  3. 代理仅通过 MCP 使用 Zapper 数据——代理仓库中的 lib/zapper.ts 将不再使用

并非所有工具都需要向 Mastra 代理公开;这是第 10 天的设计决策。


工具参考

get_portfolio(address, networks?)

完整的投资组合分解:总美元价值、所有代币持仓、所有 DeFi 头寸。

address   — wallet address or ENS name
networks  — optional array: ["ethereum", "base", "arbitrum", ...]

get_token_balances(address, networks?)

仅现货代币余额(无 DeFi 头寸)。

get_app_positions(address, networks?, app_slug?)

仅 DeFi 应用头寸(Aave、Uniswap、Sablier 等)。

app_slug  — optional filter: "aave-v3", "uniswap-v3", ...

资源:zapper://supported-networks

所有已索引网络的 { name, chainId } JSON 数组。由主机在上下文组装时读取。

提示词:analyze-wallet

预先启动投资组合分析对话。接受一个 address 参数。


错误处理

每个工具在以下情况下返回 isError: true 以及模型可操作的消息:

  • HTTP 401 / API 密钥无效

  • HTTP 429 / 速率限制

  • HTTP 5xx / Zapper 服务器错误

  • 网络超时 (15s)

  • 格式错误的响应

空钱包(totalUSD: 0, tokens: [])返回 isError: false——空并不代表错误。


已知限制

  • 单密钥信任模型:服务器持有一个 ZAPPER_API_KEY 并服务于一个所有者。多租户部署需要每用户 OAuth 或传输层身份验证(带有 Bearer 令牌的 Streamable HTTP)。

  • 无缓存:每次工具调用都会访问 Zapper API。生产服务器应添加短 TTL 缓存(头寸变化缓慢)并主动遵守速率限制。

  • 无 resources/subscribe:zapper://supported-networks 是一个静态列表。实时更新需要服务器通告订阅能力并发出 notifications/resources/updated。

  • 仅 stdio 传输:Streamable HTTP 传输推迟到未来迭代。

  • 分页上限:工具每次请求最多返回 50 个代币和 20 个应用头寸。


下一步计划

第 10 天:通过 Mastra 的 MCP 客户端将此服务器接入 ../day1-wallet-agent/ 的 Mastra 钱包代理。代理将仅通过 MCP 使用 Zapper 数据,验证工具界面是否确实将能力与代理框架解耦。

Available Tools

3 tools
get_app_positionsA

DeFi app positions only (Aave lending, Uniswap LP, staking, etc.). Use when the question is about protocol exposure: 'any leveraged positions?', 'Aave borrows?', 'LP positions on Uniswap?'. Optionally filter by app slug.

Inputs: address (required), networks, app_slug.

get_portfolioA

Full portfolio breakdown for a wallet: total USD value, all token holdings, and all DeFi app positions across networks. Use this when the user wants a complete picture of what a wallet holds.

Inputs: address (required), networks.

get_token_balancesA

Spot token balances only (no DeFi positions). Use when the question is specifically about token holdings: 'does this wallet hold ETH?', 'how much USDC is on Base?'

Inputs: address (required), networks.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of wallet data: token balances, DeFi positions, or full portfolio. Descriptions clearly differentiate them, leaving no ambiguity for an agent.

    Naming Consistency5/5

    All tools follow a consistent 'get_<descriptive_noun>' pattern (get_app_positions, get_portfolio, get_token_balances), making naming predictable and readable.

    Tool Count5/5

    Three tools is well-scoped for a wallet data server, covering the core needs without excess or deficiency.

    Completeness4/5

    The set covers token balances, DeFi positions, and a combined portfolio, which forms a complete picture for most wallet queries. Missing advanced features like transaction history are acceptable for the scope.

    Related MCP Connectors

    Related MCP Servers