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 전송 및 서버 이름 zapper-mcp로 Mastra MCP 클라이언트 구성

  3. 에이전트는 MCP를 통해서만 Zapper 데이터를 소비하며, 에이전트 저장소의 lib/zapper.ts는 사용되지 않게 됨

모든 도구를 Mastra 에이전트에 노출할 필요는 없습니다. 이는 10일 차 설계 결정 사항입니다.

도구 참조

get_portfolio(address, networks?)

전체 포트폴리오 분석: 총 USD, 모든 토큰 보유량, 모든 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 서버 오류

  • 네트워크 타임아웃 (15초)

  • 잘못된 형식의 응답

빈 지갑(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