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

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:

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Write tests for your changes
Ensure tests pass: pytest
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

Zerion MCP Server

Zerion MCP Server

Features

Requirements

Installation

From Source

From PyPI (when published)

Quick Start

1. Set up your API key

2. Run the server

3. Connect with an MCP client

Claude Desktop Configuration

Configuration

Configuration File

Environment Variables

Usage Examples

Portfolio Balance

DeFi Positions

NFT Collections

Development

Setup Development Environment

Running Tests

Code Quality

Troubleshooting

Common Issues

"Configuration error: Missing required configuration: api_key"

"Timeout loading OpenAPI specification"

"Unauthorized: Invalid or missing API key"

"Rate limit exceeded"

Debug Mode

Log Interpretation

Architecture

Tech Stack

Contributing

Development Workflow

License

Support

Changelog

New MCP Servers

MCP directory API