Content
# 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](https://developers.zerion.io)
- **Git**
---
## Installation
### 1. Clone the repository
```bash
git clone https://github.com/rockyale/zerion-mcp.git
cd zerion-mcp
```
### 2. Install dependencies
```bash
npm install
```
### 3. Get your Zerion API key
Sign up for free at [developers.zerion.io](https://developers.zerion.io), go to the Dashboard, and copy your API key.
---
## Connecting to Claude Desktop
### macOS
Open the Claude Desktop config file:
```bash
open ~/Library/Application\ Support/Claude/
```
Edit `claude_desktop_config.json` (create it if it doesn't exist):
```json
{
"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:**
```json
"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:
```json
{
"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:
```bash
claude mcp add zerion \
--env ZERION_API_KEY="your_api_key_here" \
-- npx tsx /absolute/path/to/zerion-mcp/src/index.ts
```
Verify with:
```bash
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](https://developers.zerion.io) | All EVM + Solana portfolio data, transactions, DeFi positions, gas prices, swaps | ✅ API key | [docs](https://developers.zerion.io) |
| [Blockstream.info](https://blockstream.info/api) | Bitcoin address balances and transaction history | ❌ None | [docs](https://github.com/Blockstream/esplora/blob/master/API.md) |
Bitcoin xpub derivation is done **locally** using:
- [`bip32`](https://www.npmjs.com/package/bip32) — HD key derivation
- [`bitcoinjs-lib`](https://www.npmjs.com/package/bitcoinjs-lib) — address generation
- [`tiny-secp256k1`](https://www.npmjs.com/package/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
