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 にあります。要約は以下の通りです。

プリミティブ

名前

配置の理由

Tool

get_portfolio

モデル呼び出し用。アドレスごとに動的。トークンとDeFiの全内訳を返す

Tool

get_token_balances

スポットトークンの質問に特化したツール。トークン保有量のみが必要な場合に、モデルがポートフォリオ全体を解析するのを避ける

Tool

get_app_positions

DeFiの質問に特化したツール。get_portfolioと分離することで、モデルが正確な意図を表現し、焦点を絞ったスキーマを受け取れるようにする

Resource

zapper://supported-networks

静的なネットワークリスト。プロンプト構築時にホストが環境コンテキストとして注入するため、モデルはツール呼び出しの回数を消費せずに有効なネットワーク名を知ることができる

Prompt

analyze-wallet

ユーザー呼び出し型のワークフロー。アナリストのペルソナ、ツールインベントリ、ウォレットアドレスを用いて、複数ターンのポートフォリオ分析会話を事前準備する

なぜ「すべてを取得する」大きなツールを1つにしないのか？ ツールを統合すると、モデルは質問のたびに（焦点を絞った質問であっても）混合スキーマの大きなレスポンスを受け取り、解析することを強制されます。ツールの境界はスコープの宣言です。適切なツールは、推論ステップが必要とするものを正確に返します。

なぜ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を再起動します。3つのツール、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. Mastra MCPクライアントをstdioトランスポート、サーバー名 zapper-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 を返します。空であることはエラーではありません。

既知の制限

  • シングルキー信頼モデル：サーバーは1つの ZAPPER_API_KEY を保持し、1人の所有者にサービスを提供します。マルチテナント展開には、ユーザーごとの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