Skip to main content
Glama
deenesjakoruzh
mehdi-loup

zapper-mcp

by mehdi-loup
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

zapper-mcp

Ein MCP-Server, der die Zapper DeFi-Portfolio-API als durchdachte Tool-Oberfläche für LLM-Clients bereitstellt. Verbinden Sie ihn mit Claude Desktop oder einem beliebigen MCP-kompatiblen Host und stellen Sie Fragen in natürlicher Sprache zu jedem Wallet – „Was ist dieses Wallet wert?“, „Hat es irgendwelche Aave-Positionen?“, „Zeige mir die Top-Bestände auf Base.“

Entwickelt an Tag 9 eines 21-tägigen KI-Engineering-Sprints. Tag 10 bindet diesen Server in einen Mastra-Agenten ein.

Tool-Oberfläche

Die Design-Begründung für jedes Primitive finden Sie in DESIGN.md. Die Kurzfassung:

Primitiv

Name

Warum diese Platzierung

Tool

get_portfolio

Vom Modell aufgerufen, dynamisch pro Adresse, gibt vollständige Token- + DeFi-Aufschlüsselung zurück

Tool

get_token_balances

Fokussiertes Tool für Spot-Token-Fragen; verhindert, dass das Modell ein vollständiges Portfolio parsen muss, wenn es nur Token-Bestände benötigt

Tool

get_app_positions

Fokussiertes Tool für DeFi-Fragen; getrennt von get_portfolio, damit das Modell präzise Absichten ausdrücken und ein fokussiertes Schema erhalten kann

Ressource

zapper://supported-networks

Statische Netzwerkliste – der Host fügt sie zur Zeit der Prompt-Erstellung als Umgebungskontext ein, damit das Modell gültige Netzwerknamen kennt, ohne einen Tool-Aufruf zu verbrauchen

Prompt

analyze-wallet

Vom Benutzer aufgerufener Workflow, der eine mehrstufige Portfolio-Analyse-Konversation mit Analysten-Persona, Tool-Inventar und Wallet-Adresse vorinitialisiert

Warum nicht ein großes get_everything-Tool? Das Zusammenfassen der Tools würde das Modell zwingen, für jede Frage eine große Antwort mit gemischtem Schema zu empfangen und zu parsen, selbst bei fokussierten Fragen. Eine Tool-Grenze ist eine Deklaration des Geltungsbereichs – das richtige Tool gibt genau das zurück, was der Argumentationsschritt benötigt.

Warum ist der API-Schlüssel in der Serverkonfiguration und nicht als Tool-Argument? Anmeldedaten gehören in die Host-Ebene (Umgebungsvariablen, die beim Prozessstart eingefügt werden), nicht in das MCP-Protokoll. Wenn api_key ein Tool-Parameter wäre, würde er durch die Argumentation des LLM fließen und im Konversationsverlauf erscheinen. Für eine Multi-Tenant-Bereitstellung ist der richtige Mechanismus eine Authentifizierung auf Transportebene (Bearer-Token über Streamable HTTP) oder OAuth pro Benutzer – beides ist hier nicht vorgesehen. Siehe Bekannte Einschränkungen.

Related MCP server: Ankr API MCP Server

Anforderungen

Installation

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

Konfiguration

Kopieren Sie .env.example nach .env und fügen Sie Ihren Schlüssel hinzu:

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

Der Server schlägt beim Start sofort fehl, wenn ZAPPER_API_KEY fehlt – Sie sehen den Fehler sofort, nicht erst beim ersten Tool-Aufruf.

Ausführen

Standalone-Smoke-Test (bestätigt, dass alles ohne Claude Desktop funktioniert):

ZAPPER_API_KEY=your_key pnpm client

Ausgabe: listet Tools/Ressourcen/Prompts auf und ruft dann jedes Tool für vitalik.eth auf.

Direkter Serverstart:

ZAPPER_API_KEY=your_key pnpm start

Claude Desktop-Anbindung

Hinzufügen zu ~/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"
      }
    }
  }
}

Starten Sie Claude Desktop neu. Die drei Tools, die Ressource zapper://supported-networks und der Prompt analyze-wallet werden verfügbar sein.

Protokolle (falls der Server nicht geladen werden kann):

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

Mastra-Integration (Tag 10)

Um diesen Server über den MCP-Client von Mastra in einen Mastra-Agenten einzubinden:

  1. Starten Sie den Server: node /path/to/build/server.js

  2. Konfigurieren Sie den Mastra MCP-Client mit stdio-Transport, Servername zapper-mcp

  3. Der Agent konsumiert Zapper-Daten ausschließlich über MCP – lib/zapper.ts im Agent-Repo wird ungenutzt

Nicht alle Tools müssen für den Mastra-Agenten freigegeben werden; das ist eine Design-Entscheidung für Tag 10.

Tool-Referenz

get_portfolio(address, networks?)

Vollständige Portfolio-Aufschlüsselung: USD-Gesamtwert, alle Token-Bestände, alle DeFi-Positionen.

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

get_token_balances(address, networks?)

Nur Spot-Token-Guthaben (keine DeFi-Positionen).

get_app_positions(address, networks?, app_slug?)

Nur DeFi-App-Positionen (Aave, Uniswap, Sablier, etc.).

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

Ressource: zapper://supported-networks

JSON-Array von { name, chainId } für alle indizierten Netzwerke. Wird vom Host zur Zeit der Kontext-Erstellung gelesen.

Prompt: analyze-wallet

Initialisiert eine Portfolio-Analyse-Konversation vor. Erfordert ein address-Argument.

Fehlerbehandlung

Jedes Tool gibt isError: true mit einer für das Modell umsetzbaren Nachricht zurück bei:

  • HTTP 401 / ungültiger API-Schlüssel

  • HTTP 429 / Ratenbegrenzung überschritten

  • HTTP 5xx / Zapper-Serverfehler

  • Netzwerk-Timeout (15s)

  • Fehlerhafte Antwort

Ein leeres Wallet (totalUSD: 0, tokens: []) gibt isError: false zurück – leer ist kein Fehler.

Bekannte Einschränkungen

  • Single-Key-Vertrauensmodell: Der Server hält einen ZAPPER_API_KEY und bedient einen Eigentümer. Eine Multi-Tenant-Bereitstellung erfordert OAuth pro Benutzer oder eine Authentifizierung auf Transportebene (Streamable HTTP mit Bearer-Token).

  • Kein Caching: Jeder Tool-Aufruf greift auf die Zapper-API zu. Ein Produktionsserver würde einen Cache mit kurzer TTL hinzufügen (Positionen ändern sich langsam) und Ratenbegrenzungen proaktiv einhalten.

  • Kein resources/subscribe: zapper://supported-networks ist eine statische Liste. Live-Updates würden erfordern, dass der Server die Abonnement-Fähigkeit ankündigt und notifications/resources/updated ausgibt.

  • Nur stdio-Transport: Streamable HTTP-Transport wurde auf eine zukünftige Iteration verschoben.

  • Paginierungsgrenze: Tools geben bis zu 50 Token und 20 App-Positionen pro Anfrage zurück.

Was kommt als Nächstes

Tag 10: Einbindung dieses Servers in den Mastra-Wallet-Agenten unter ../day1-wallet-agent/ über den MCP-Client von Mastra. Der Agent wird Zapper-Daten ausschließlich über MCP konsumieren und damit validieren, dass die Tool-Oberfläche die Funktionalität tatsächlich vom Agent-Framework entkoppelt.

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