Skip to main content
Glama
deenesjakoruzh
mehdi-loup

zapper-mcp

by mehdi-loup
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesWallet address or ENS name
networksNoNetworks to filter by. Supported: ethereum, base, optimism, arbitrum, polygon, bnb, avalanche, zora. Omit for all networks.
app_slugNoFilter to a specific app slug, e.g. 'aave-v3', 'uniswap-v3'

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but does not disclose behavioral traits such as read-only nature, data freshness, or performance characteristics. The description only mentions filtering capabilities, which is adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: first defines scope, second provides usage context and optional filter. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does not explain return values. However, given the tool's simplicity (3 params, 1 required) and clear purpose, the description is largely complete. Minor gap in output expectations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% coverage with descriptions for each parameter. The description does not add semantic value beyond the schema, simply restating the optional app_slug filter. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'DeFi app positions only' and lists examples (Aave, Uniswap, staking), clearly distinguishing it from sibling tools like get_portfolio and get_token_balances.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description directly tells when to use the tool ('when the question is about protocol exposure') and provides example queries ('any leveraged positions?', 'Aave borrows?', 'LP positions on Uniswap?'), effectively guiding the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesWallet address or ENS name
networksNoNetworks to filter by. Supported: ethereum, base, optimism, arbitrum, polygon, bnb, avalanche, zora. Omit for all networks.

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Discloses output (breakdown) but no information about side effects, permissions, rate limits, or data freshness. Lacks behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences. First describes output, second specifies usage context. No wasted words, front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, so description must compensate. It explains return includes USD value, tokens, DeFi positions, but lacks detail on structure (e.g., token amounts, symbols). Adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. Description adds little beyond schema: repeats networks list and 'Omit for all networks' which is already in the schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides a full portfolio breakdown including total USD value, token holdings, and DeFi positions. It distinguishes itself from siblings (get_app_positions, get_token_balances) which are subsets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to use when user wants a complete picture of wallet holdings. Does not list when to avoid using or mention alternatives, but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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?'

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesWallet address or ENS name
networksNoNetworks to filter by. Supported: ethereum, base, optimism, arbitrum, polygon, bnb, avalanche, zora. Omit for all networks.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the scope (spot tokens only) but does not mention any other behavioral traits such as rate limits, authentication requirements, or response format. Acceptable but could be more comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, front-loaded sentences with no redundant information. Every word contributes to clarity and utility.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only two parameters and no output schema, the description is reasonably complete: it states scope, use cases, and exclusions. It could briefly hint at output structure, but that is not critical for this simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds minor value by providing usage examples but does not elaborate on parameter semantics beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns 'spot token balances only' and explicitly excludes DeFi positions, distinguishing it from siblings like get_app_positions. It also provides specific example queries, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use when the question is specifically about token holdings' and gives concrete examples. It implies when not to use (DeFi positions) but does not directly name alternative tools for that case. Still, the guidance is clear and helpful.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
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.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mehdi-loup/zapper-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server