Skip to main content
Glama
deenesjakoruzh
mehdi-loup

zapper-mcp

by mehdi-loup
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

zapper-mcp

An MCP server that exposes the Zapper DeFi portfolio API as a thoughtfully designed tool surface for LLM clients. Connect it to Claude Desktop or any MCP-compatible host and ask natural-language questions about any wallet — "what is this wallet worth?", "does it have any Aave positions?", "show me the top holdings on Base."

Built on Day 9 of a 21-day AI engineering sprint. Day 10 wires this server into a Mastra agent.

Tool surface

The design rationale for each primitive is in DESIGN.md. The short version:

Primitive

Name

Why this placement

Tool

get_portfolio

Model-invoked, dynamic per address, returns full token + DeFi breakdown

Tool

get_token_balances

Focused tool for spot-token questions; avoids making the model parse a full portfolio when it only needs token holdings

Tool

get_app_positions

Focused tool for DeFi questions; separate from get_portfolio so the model can express precise intent and receive a focused schema

Resource

zapper://supported-networks

Static network list — host injects it as ambient context at prompt-assembly time so the model knows valid network names without burning a tool-call turn

Prompt

analyze-wallet

User-invoked workflow that pre-seeds a multi-turn portfolio analysis conversation with analyst persona, tool inventory, and wallet address

Why not one big get_everything tool? Collapsing the tools would force the model to receive and parse a large mixed-schema response for every question, even focused ones. A tool boundary is a declaration of scope — the right tool returns exactly what the reasoning step needs.

Why is the API key in server config, not a tool argument? Credentials belong in the host layer (env vars injected at process spawn), not in the MCP protocol. If api_key were a tool parameter, it would flow through the LLM's reasoning and appear in conversation history. For a multi-tenant deploy the right mechanism is transport-layer auth (Bearer token over Streamable HTTP) or per-user OAuth — both out of scope here. See Known limitations.

Related MCP server: Ankr API MCP Server

Requirements

Install

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

Configuration

Copy .env.example to .env and add your key:

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

The server fails fast at boot if ZAPPER_API_KEY is missing — you'll see the error immediately, not on the first tool call.

Run

Standalone smoke test (confirms everything works without Claude Desktop):

ZAPPER_API_KEY=your_key pnpm client

Output: lists tools/resources/prompts, then calls each tool against vitalik.eth.

Direct server start:

ZAPPER_API_KEY=your_key pnpm start

Claude Desktop wiring

Add to ~/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"
      }
    }
  }
}

Restart Claude Desktop. The three tools, the zapper://supported-networks resource, and the analyze-wallet prompt will be available.

Logs (if the server fails to load):

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

Mastra integration (Day 10)

To wire this server into a Mastra agent via Mastra's MCP client:

  1. Start the server: node /path/to/build/server.js

  2. Configure the Mastra MCP client with stdio transport, server name zapper-mcp

  3. The agent consumes Zapper data exclusively through MCP — lib/zapper.ts in the agent repo becomes unused

Not all tools need to be exposed to the Mastra agent; that's a Day 10 design call.

Tool reference

get_portfolio(address, networks?)

Full portfolio breakdown: total USD, all token holdings, all DeFi positions.

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

get_token_balances(address, networks?)

Spot token balances only (no DeFi positions).

get_app_positions(address, networks?, app_slug?)

DeFi app positions only (Aave, Uniswap, Sablier, etc.).

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

Resource: zapper://supported-networks

JSON array of { name, chainId } for all indexed networks. Read by host at context-assembly time.

Prompt: analyze-wallet

Pre-seeds a portfolio analysis conversation. Takes an address argument.

Error handling

Every tool returns isError: true with a model-actionable message on:

  • HTTP 401 / invalid API key

  • HTTP 429 / rate limited

  • HTTP 5xx / Zapper server error

  • Network timeout (15s)

  • Malformed response

An empty wallet (totalUSD: 0, tokens: []) returns isError: false — empty is not an error.

Known limitations

  • Single-key trust model: the server holds one ZAPPER_API_KEY and serves one owner. A multi-tenant deploy needs per-user OAuth or transport-layer auth (Streamable HTTP with Bearer tokens).

  • No caching: every tool call hits the Zapper API. A production server would add a short TTL cache (positions change slowly) and respect rate limits proactively.

  • No resources/subscribe: zapper://supported-networks is a static list. Live updates would require the server to advertise subscribe capability and emit notifications/resources/updated.

  • stdio transport only: Streamable HTTP transport deferred to a future iteration.

  • Pagination ceiling: tools return up to 50 tokens and 20 app positions per request.

What's next

Day 10: wire this server into the Mastra wallet agent at ../day1-wallet-agent/ via Mastra's MCP client. The agent will consume Zapper data exclusively through MCP, validating that the tool surface actually decouples the capability from the agent framework.

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