Odos MCP Client

A Model Context Protocol (MCP) client for interacting with the Odos DEX aggregation platform and Zerion portfolio analytics. This tool provides comprehensive access to DeFi trading data, swap quotes, portfolio analysis, and transaction history across multiple blockchain networks.

Features

Odos API Integration

Swap Quotes: Get optimal swap routes and pricing across DEX liquidity sources
Zap Operations: Single-transaction liquidity provision quotes
Chain Support: Access all Odos-supported blockchain networks
Token Data: Real-time pricing and metadata for supported tokens
Router Information: Contract addresses and blockchain infrastructure details

Zerion Analytics

Portfolio Analysis: Complete wallet holdings and composition breakdown
Transaction History: Detailed historical transaction data and analysis
Performance Tracking: Historical portfolio performance and returns
Gas Price Monitoring: Real-time gas estimates across networks

Installation

# Clone the repository
git clone <repository-url>
cd odos-mcp

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
# Create a .env file and add your API keys (see Configuration section)
# Or set environment variables directly:
export ZERION_API_KEY="your_zerion_api_key_here"

# Verify setup (optional but recommended)
python scripts/verify_setup.py

Usage

Ensure you have set up the required environment variables (see Configuration section), then start the MCP server:

poetry run python -m src.client.server

Note: Make sure ZERION_API_KEY is set if you plan to use any Zerion analytics tools.

Verifying Your Setup

Run the verification script to ensure everything is configured correctly:

python scripts/verify_setup.py

This script will:

Test all module imports
Verify environment configuration
Check API connectivity
Validate helper functions
Provide a comprehensive setup report

Available Tools

API Tools (`src/client/tools/api/`)

Tool	Description
`get_quote_swap`	Get swap quotes and transaction data
`get_quote_zap`	Get zap quotes for liquidity provision
`get_supported_chains`	List supported blockchain networks
`get_supported_tokens`	Retrieve tradeable tokens by chain
`get_token_price`	Real-time token pricing data
`get_chain_token_prices`	Bulk token prices across chains
`get_currencies`	Fiat currency exchange rates
`get_contract_info`	Smart contract details and metadata
`get_router_address`	Odos router contract addresses
`get_current_block`	Current block numbers and network status
`get_liquidity_sources`	Available DEX integrations

Zerion Tools (`src/client/tools/zerion/`)

Note: These tools require the ZERION_API_KEY environment variable to be set.

Tool	Description
`get_wallet_portfolio`	Portfolio holdings and composition
`get_past_transactions`	Historical transaction analysis
`get_past_performance`	Portfolio performance tracking
`get_gas_prices`	Network gas price estimates

Project Structure

odos-mcp/
├── src/client/                 # Core client package
│   ├── tools/                  # Tool implementations
│   │   ├── api/               # Odos API tools
│   │   └── zerion/            # Zerion integration tools
│   ├── constants.py           # Chain IDs, token addresses, API endpoints
│   ├── helpers.py             # Utility functions for API requests
│   ├── mcp_types.py          # Pydantic models for API responses
│   └── api_models.py         # Additional data models
├── scripts/                   # Development and maintenance scripts
│   ├── verify_setup.py        # Setup verification script
│   └── ...
├── tests/                     # Test suite
└── requirements.txt          # Python dependencies

Configuration

Environment Variables

The client requires the following environment variables:

# Required: Zerion API Key for portfolio analytics
export ZERION_API_KEY="your_zerion_api_key_here"

Getting API Keys

Zerion API Key

To use Zerion analytics tools, you'll need a Zerion API key:

Visit Zerion Developer Portal
Sign up for a developer account
Create a new API key
Set the ZERION_API_KEY environment variable

Setting Environment Variables

Create a .env file in the project root:

# .env file
ZERION_API_KEY=your_zerion_api_key_here

Or set them directly in your shell:

export ZERION_API_KEY="your_zerion_api_key_here"

API Endpoints

The following API endpoints are used (hardcoded in the application):

Odos API: https://api.odos.xyz (no authentication required)
Zerion API: https://api.zerion.io (requires API key)

Development

Setup Development Environment

# Install development dependencies
pip install -r requirements-dev.txt

# Run formatting
python scripts/format.py

# Run tests

Adding New Tools

Create tool file in appropriate directory (api/ or zerion/)
Add brief description docstring
Implement using FastMCP decorator pattern
Update __init__.py exports
Add tests in tests/ directory

Contributing

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For questions or issues:

Create an issue in the repository
Check existing documentation and tool descriptions
Review the Odos API documentation for parameter details

Odos