Skip to main content
Glama
deenesjakoruzh
mehdi-loup

zapper-mcp

by mehdi-loup
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

zapper-mcp

Un servidor MCP que expone la API de portafolio DeFi de Zapper como una superficie de herramientas cuidadosamente diseñada para clientes LLM. Conéctalo a Claude Desktop o a cualquier host compatible con MCP y haz preguntas en lenguaje natural sobre cualquier billetera: "¿cuánto vale esta billetera?", "¿tiene alguna posición en Aave?", "muéstrame las principales tenencias en Base".

Construido en el día 9 de un sprint de ingeniería de IA de 21 días. El día 10 conecta este servidor a un agente de Mastra.

Superficie de herramientas

La justificación del diseño para cada primitiva se encuentra en DESIGN.md. La versión corta:

Primitiva

Nombre

¿Por qué esta ubicación?

Herramienta

get_portfolio

Invocada por el modelo, dinámica por dirección, devuelve el desglose completo de tokens + DeFi

Herramienta

get_token_balances

Herramienta enfocada para preguntas sobre tokens al contado; evita que el modelo analice un portafolio completo cuando solo necesita tenencias de tokens

Herramienta

get_app_positions

Herramienta enfocada para preguntas sobre DeFi; separada de get_portfolio para que el modelo pueda expresar una intención precisa y recibir un esquema enfocado

Recurso

zapper://supported-networks

Lista estática de redes: el host la inyecta como contexto ambiental al momento de ensamblar el prompt para que el modelo conozca los nombres de red válidos sin gastar un turno de llamada de herramienta

Prompt

analyze-wallet

Flujo de trabajo invocado por el usuario que pre-configura una conversación de análisis de portafolio de varios turnos con una personalidad de analista, inventario de herramientas y dirección de billetera

¿Por qué no una gran herramienta get_everything? Colapsar las herramientas obligaría al modelo a recibir y analizar una respuesta de esquema mixto grande para cada pregunta, incluso las enfocadas. Un límite de herramienta es una declaración de alcance: la herramienta correcta devuelve exactamente lo que el paso de razonamiento necesita.

¿Por qué la clave API está en la configuración del servidor y no como argumento de herramienta? Las credenciales pertenecen a la capa del host (variables de entorno inyectadas al iniciar el proceso), no al protocolo MCP. Si api_key fuera un parámetro de herramienta, fluiría a través del razonamiento del LLM y aparecería en el historial de la conversación. Para un despliegue multi-inquilino, el mecanismo correcto es la autenticación en la capa de transporte (token Bearer sobre HTTP transmitible) o OAuth por usuario; ambos fuera del alcance aquí. Ver Limitaciones conocidas.

Related MCP server: Ankr API MCP Server

Requisitos

Instalación

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

Configuración

Copia .env.example a .env y añade tu clave:

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

El servidor falla rápidamente al arrancar si falta ZAPPER_API_KEY: verás el error inmediatamente, no en la primera llamada a la herramienta.

Ejecución

Prueba de humo independiente (confirma que todo funciona sin Claude Desktop):

ZAPPER_API_KEY=your_key pnpm client

Salida: enumera herramientas/recursos/prompts, luego llama a cada herramienta contra vitalik.eth.

Inicio directo del servidor:

ZAPPER_API_KEY=your_key pnpm start

Conexión con Claude Desktop

Añade a ~/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"
      }
    }
  }
}

Reinicia Claude Desktop. Las tres herramientas, el recurso zapper://supported-networks y el prompt analyze-wallet estarán disponibles.

Registros (si el servidor no logra cargar):

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

Integración con Mastra (Día 10)

Para conectar este servidor a un agente de Mastra a través del cliente MCP de Mastra:

  1. Inicia el servidor: node /path/to/build/server.js

  2. Configura el cliente MCP de Mastra con transporte stdio, nombre del servidor zapper-mcp

  3. El agente consume datos de Zapper exclusivamente a través de MCP: lib/zapper.ts en el repositorio del agente queda sin uso

No todas las herramientas necesitan estar expuestas al agente de Mastra; esa es una decisión de diseño del Día 10.

Referencia de herramientas

get_portfolio(address, networks?)

Desglose completo del portafolio: USD total, todas las tenencias de tokens, todas las posiciones DeFi.

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

get_token_balances(address, networks?)

Solo saldos de tokens al contado (sin posiciones DeFi).

get_app_positions(address, networks?, app_slug?)

Solo posiciones de aplicaciones DeFi (Aave, Uniswap, Sablier, etc.).

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

Recurso: zapper://supported-networks

Matriz JSON de { name, chainId } para todas las redes indexadas. Leído por el host al momento de ensamblar el contexto.

Prompt: analyze-wallet

Pre-configura una conversación de análisis de portafolio. Toma un argumento address.

Manejo de errores

Cada herramienta devuelve isError: true con un mensaje procesable por el modelo en caso de:

  • HTTP 401 / clave API inválida

  • HTTP 429 / límite de tasa excedido

  • HTTP 5xx / error del servidor de Zapper

  • Tiempo de espera de red (15s)

  • Respuesta mal formada

Una billetera vacía (totalUSD: 0, tokens: []) devuelve isError: false: estar vacío no es un error.

Limitaciones conocidas

  • Modelo de confianza de una sola clave: el servidor mantiene una ZAPPER_API_KEY y sirve a un propietario. Un despliegue multi-inquilino necesita OAuth por usuario o autenticación en la capa de transporte (HTTP transmitible con tokens Bearer).

  • Sin caché: cada llamada a la herramienta golpea la API de Zapper. Un servidor de producción añadiría una caché de TTL corto (las posiciones cambian lentamente) y respetaría los límites de tasa de forma proactiva.

  • Sin resources/subscribe: zapper://supported-networks es una lista estática. Las actualizaciones en vivo requerirían que el servidor anuncie la capacidad de suscripción y emita notifications/resources/updated.

  • Solo transporte stdio: el transporte HTTP transmitible se pospuso para una iteración futura.

  • Límite de paginación: las herramientas devuelven hasta 50 tokens y 20 posiciones de aplicaciones por solicitud.

¿Qué sigue?

Día 10: conectar este servidor al agente de billetera de Mastra en ../day1-wallet-agent/ a través del cliente MCP de Mastra. El agente consumirá datos de Zapper exclusivamente a través de MCP, validando que la superficie de herramientas realmente desacople la capacidad del marco de trabajo del agente.

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