zerion-mcp

A local MCP (Model Context Protocol) server that gives Claude Desktop and Claude Code live access to your crypto portfolio — powered by the Zerion API for EVM + Solana chains, and Blockstream for Bitcoin.

Once connected, you can ask Claude things like:

• "What's my total portfolio value across Ethereum and Base?"
• "Show my Uniswap LP positions"
• "What's my Bitcoin balance from this xpub?"
• "What are current gas prices on Arbitrum and Optimism?"
• "Get swap offers to trade 1 ETH for USDC"

---

Prerequisites

• Node.js v18 or higher (node --version to check)
• npm v8 or higher
• Zerion API key — free tier available at developers.zerion.io
• Git

---

Installation

1. Clone the repository

git clone https://github.com/rockyale/zerion-mcp.git
cd zerion-mcp

2. Install dependencies

npm install

3. Get your Zerion API key

Sign up for free at developers.zerion.io, go to the Dashboard, and copy your API key.

---

Connecting to Claude Desktop

macOS

Open the Claude Desktop config file:

open ~/Library/Application\ Support/Claude/

Edit claude_desktop_config.json (create it if it doesn't exist):

{
  "mcpServers": {
    "zerion": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/zerion-mcp/src/index.ts"],
      "env": {
        "ZERION_API_KEY": "your_api_key_here"
      }
    }
  }
}

Replace /absolute/path/to/zerion-mcp with the actual path. To find it, run pwd inside the project folder.

Example:

"args": ["tsx", "/Users/yourname/projects/zerion-mcp/src/index.ts"]

Windows

Open the Claude Desktop config file at:

%APPDATA%\Claude\claude_desktop_config.json

You can open it by pressing Win + R, typing %APPDATA%\Claude and hitting Enter.

Edit the file:

{
  "mcpServers": {
    "zerion": {
      "command": "npx",
      "args": ["tsx", "C:\\Users\\yourname\\projects\\zerion-mcp\\src\\index.ts"],
      "env": {
        "ZERION_API_KEY": "your_api_key_here"
      }
    }
  }
}

Note: use double backslashes \\ in Windows paths.

After editing the config

Fully quit Claude Desktop (not just close the window) and reopen it. To confirm your Zerion MCP tools are loaded, click + in chat input and look for Zerion listed there in connectors — if it's showing, you're good to go.

---

Connecting to Claude Code

Run this once in your terminal:

claude mcp add zerion \
  --env ZERION_API_KEY="your_api_key_here" \
  -- npx tsx /absolute/path/to/zerion-mcp/src/index.ts

Verify with:

claude mcp list

---

Available Tools

Wallet

Tool	Description
get_wallet_portfolio	Total portfolio value, breakdown by chain and position type
get_wallet_fungible_positions	Token and DeFi protocol positions (supports Uniswap, Aave, etc.)
get_wallet_transactions	Full transaction history with decoded action types
get_wallet_pnl	Realized and unrealized PnL using FIFO accounting
get_wallet_nft_positions	NFTs held by a wallet
get_wallet_nft_portfolio	NFT portfolio overview and total value
get_wallet_balance_chart	Historical portfolio balance over time

Wallet Sets (multi-wallet aggregation)

Tool	Description
get_wallet_set_portfolio	Aggregated portfolio across EVM + Solana wallet pair
get_wallet_set_fungible_positions	Aggregated token positions across wallet set
get_wallet_set_pnl	Aggregated PnL across wallet set
get_wallet_set_transactions	Aggregated transaction history across wallet set

Tokens

Tool	Description
search_fungibles	Search tokens by name, symbol, or contract address
get_fungible_by_id	Detailed token info by Zerion ID
get_fungible_chart	Token price chart over a time period

Chains & Gas

Tool	Description
get_chains	All blockchain networks supported by Zerion
get_gas_prices	Real-time gas prices across all supported chains

Swap

Tool	Description
get_swap_offers	Swap/bridge quotes from aggregated providers (1inch, ParaSwap, 0x) with ready-to-sign transaction data

Bitcoin

Tool	Description
get_bitcoin_address_info	Balance and stats for a single Bitcoin address (legacy, SegWit, native SegWit)
get_bitcoin_transactions	Recent transaction history for a Bitcoin address
get_bitcoin_xpub_balance	Full HD wallet balance from an xpub/zpub key — derives all child addresses and sums balance (for Ledger and other HD wallets)

---

Getting your Bitcoin xpub (Ledger)

If you use Ledger Live with Native SegWit (bc1 addresses):

1. Open Ledger Live
2. Go to your Bitcoin account
3. Click the three dots → Edit account → Advanced
4. Copy the xpub key

Paste it into Claude: "Get my Bitcoin balance from this xpub: xpub6..."

---

External Services

Service	Used for	Auth required	Docs
Zerion API	All EVM + Solana portfolio data, transactions, DeFi positions, gas prices, swaps	✅ API key	docs
Blockstream.info	Bitcoin address balances and transaction history	❌ None	docs

Bitcoin xpub derivation is done locally using:

• bip32 — HD key derivation
• bitcoinjs-lib — address generation
• tiny-secp256k1 — elliptic curve cryptography

No private keys are ever required or used. The xpub is a read-only key — it can only derive public addresses.

---

Project Structure

zerion-mcp/
├── src/
│   ├── index.ts       # MCP server entry point, stdio transport
│   ├── tools.ts       # Tool definitions and input schemas
│   ├── handlers.ts    # Maps tool calls to API requests
│   └── client.ts      # Zerion API auth, fetch wrapper, pagination
├── package.json
├── tsconfig.json
└── README.md

---

Security notes

• Your Zerion API key is passed via environment variable and never hardcoded
• The xpub key is read-only — it cannot sign transactions or move funds
• Never commit your API key to git — add .env to .gitignore if you use one
• For team use, share the repo without keys and let each developer set ZERION_API_KEY in their own shell profile

---

Troubleshooting

Tools not showing up in Claude Desktop

• Make sure you fully quit and reopened Claude Desktop after editing the config
• Check the path in the config points to the correct src/index.ts
• Run tail -f ~/Library/Logs/Claude/mcp-server-zerion.log (macOS) to see errors

fetch failed on Bitcoin tools

• This can happen if Blockstream rate-limits rapid requests — the server includes a 150ms delay between address queries to avoid this
• If it persists, try again after a few seconds

ZERION_API_KEY not set error

• Make sure the key is set in the env block of your claude_desktop_config.json
• Double-check there are no extra spaces or quotes around the key value

Uniswap / DeFi positions not showing

• Make sure to pass filter_positions: no_filter when asking for positions, otherwise only simple wallet tokens are returned by default