Zerion MCP Server

A production-ready Model Context Protocol (MCP) server that provides AI assistants with access to the Zerion API for cryptocurrency portfolio management, DeFi positions, NFTs, and market data.

Features

• 🔌 Auto-generated Tools: Automatically exposes Zerion API endpoints as MCP tools via OpenAPI specification
• ⚙️ Flexible Configuration: YAML config files with environment variable overrides
• 📝 Structured Logging: JSON and text formats with sensitive data redaction
• 🛡️ Robust Error Handling: Custom exceptions with detailed context and troubleshooting hints
• ✅ Comprehensive Tests: Unit and integration tests with pytest
• 🚀 Async HTTP: Non-blocking API calls with httpx

Available Functions

• getChainById: Returns a chain by its unique chain identifier.
• getFungibleById: Returns a fungible asset by its unique identifier.
• getFungibleChart: Returns the chart for a fungible asset for a selected period.
• getNFTById: Returns a single NFT by its unique identifier.
• getWalletChart: Returns a portfolio balance chart for a wallet.
• getWalletNftPortfolio: Returns the NFT portfolio overview of a web3 wallet.
• getWalletPNL: Returns the Profit and Loss (PnL) details of a web3 wallet.
• getWalletPortfolio: Returns the portfolio overview of a web3 wallet.
• listChains: Returns a list of all chains supported by Zerion.
• listFungibles: Returns a paginated list of fungible assets supported by Zerion.
• listGasPrices: Provides real-time information on the current gas prices across all supported blockchain networks.
• listNFTs: Returns a list of NFTs by using different parameters.
• listWalletNFTCollections: Returns a list of the NFT collections held by a specific wallet.
• listWalletNFTPositions: Returns a list of the NFT positions held by a specific wallet.
• listWalletPositions: Returns a list of wallet positions.
• listWalletTransactions: Returns a list of transactions associated with the wallet.
• swapFungibles: Provides a list of fungibles available for bridge exchange.
• swapOffers: Provides a comprehensive overview of relevant trades and bridge exchanges.

Requirements

• Python 3.11 or higher
• Zerion API key (Get one here)

Installation

From Source

# Clone the repository
git clone https://github.com/SAK1337/myzerionmcp.git
cd myzerionmcp

# Install the package
pip install -e .

# For development (includes testing dependencies)
pip install -e ".[dev]"

From PyPI (when published)

pip install zerion-mcp-server

Quick Start

1. Set up your API key

export ZERION_API_KEY="Bearer your-api-key-here"

2. Run the server

zerion-mcp-server

3. Connect with an MCP client

The server will start and listen for MCP protocol connections. You can connect it to AI assistants like Claude Desktop.

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "zerion": {
      "command": "zerion-mcp-server",
      "env": {
        "ZERION_API_KEY": "Bearer your-api-key-here"
      }
    }
  }
}

Configuration

Configuration File

Create a config.yaml file in your working directory:

# Server configuration
name: "Zerion API"
base_url: "https://api.zerion.io"
oas_url: "https://raw.githubusercontent.com/smart-mcp-proxy/zerion-mcp-server/main/zerion_mcp_server/openapi_zerion.yaml"

# API authentication
api_key: "${ZERION_API_KEY}"  # Environment variable substitution

# Logging configuration
logging:
  level: "INFO"      # DEBUG, INFO, WARN, ERROR
  format: "text"     # text or json

See config.example.yaml for a complete example.

Environment Variables

Environment variables override config file values:

Variable	Description	Default
ZERION_API_KEY	Zerion API key (required)	-
ZERION_BASE_URL	Zerion API base URL	https://api.zerion.io
ZERION_OAS_URL	OpenAPI spec URL	GitHub raw URL
CONFIG_PATH	Path to config.yaml	./config.yaml
LOG_LEVEL	Logging level	INFO
LOG_FORMAT	Logging format (text/json)	text

Usage Examples

Once connected to an MCP client (like Claude), you can query Zerion data:

Portfolio Balance

Get the portfolio balance for wallet 0x1234...

The server exposes tools like getWalletChart, getWalletPositions, etc.

DeFi Positions

Show me the DeFi positions for address 0xabcd...

NFT Collections

List NFTs owned by 0x5678...

All Zerion API endpoints are automatically available as MCP tools. See the Zerion API documentation for available operations.

Development

Setup Development Environment

# Clone and install with dev dependencies
git clone https://github.com/SAK1337/myzerionmcp.git
cd myzerionmcp
pip install -e ".[dev]"

# Set up API key
export ZERION_API_KEY="Bearer your-test-key"

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=zerion_mcp_server --cov-report=html

# Run specific test file
pytest tests/test_config.py

# Run with verbose output
pytest -v

Code Quality

# Type checking (if mypy is installed)
mypy zerion_mcp_server

# Linting (if ruff is installed)
ruff check zerion_mcp_server

Troubleshooting

Common Issues

"Configuration error: Missing required configuration: api_key"

Solution: Set the ZERION_API_KEY environment variable:

export ZERION_API_KEY="Bearer your-api-key-here"

"Timeout loading OpenAPI specification"

Solution: Check your internet connection. The server needs to download the OpenAPI spec from GitHub.

"Unauthorized: Invalid or missing API key"

Solution: Verify your API key is correct and includes the "Bearer " prefix:

export ZERION_API_KEY="Bearer your-actual-key"

"Rate limit exceeded"

Solution: Wait for the rate limit window to reset. Check the error message for retry_after_sec value.

Debug Mode

Enable debug logging for detailed information:

export LOG_LEVEL="DEBUG"
zerion-mcp-server

Or in config.yaml:

logging:
  level: "DEBUG"
  format: "json"  # Structured logs for analysis

Log Interpretation

• INFO: Normal operation (startup, requests)
• WARN: Potential issues (slow operations)
• ERROR: Failures (API errors, network issues)
• DEBUG: Detailed traces (request/response bodies)

Architecture

┌─────────────────┐
│   MCP Client    │ (e.g., Claude Desktop)
│  (AI Assistant) │
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼────────┐
│  FastMCP Server │
│                 │
│  ┌───────────┐  │
│  │ Config    │  │ (YAML + Env)
│  │ Manager   │  │
│  └───────────┘  │
│                 │
│  ┌───────────┐  │
│  │  Logger   │  │ (Structured)
│  └───────────┘  │
│                 │
│  ┌───────────┐  │
│  │  Error    │  │ (Custom Exceptions)
│  │  Handler  │  │
│  └───────────┘  │
│                 │
│  ┌───────────┐  │
│  │ HTTP      │  │ (httpx AsyncClient)
│  │ Client    │  │
│  └─────┬─────┘  │
└────────┼────────┘
         │
         │ HTTPS
         │
┌────────▼────────┐
│   Zerion API    │
│                 │
│  - Portfolios   │
│  - DeFi         │
│  - NFTs         │
│  - Transactions │
└─────────────────┘

Tech Stack

• Python 3.11+: Core language
• FastMCP: MCP server framework with OpenAPI integration
• httpx: Async HTTP client
• PyYAML: Configuration parsing
• pytest: Testing framework

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Write tests for your changes
4. Ensure tests pass: pytest
5. Submit a pull request

Development Workflow

• Follow PEP 8 style guidelines
• Add type hints to function signatures
• Write docstrings for modules and functions
• Update tests for any code changes
• Keep commits focused and atomic

License

MIT License - see LICENSE file for details

Support

• Issues: GitHub Issues
• Zerion API Docs: developers.zerion.io
• MCP Specification: modelcontextprotocol.io

Changelog

See CHANGELOG.md for version history and changes