Odos MCP Server

# 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 ```bash # 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: ```bash 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: ```bash 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: ```bash # 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: 1. Visit [Zerion Developer Portal](https://zerion.io/developers) 2. Sign up for a developer account 3. Create a new API key 4. Set the `ZERION_API_KEY` environment variable ### Setting Environment Variables Create a `.env` file in the project root: ```bash # .env file ZERION_API_KEY=your_zerion_api_key_here ``` Or set them directly in your shell: ```bash 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 ```bash # Install development dependencies pip install -r requirements-dev.txt # Run formatting python scripts/format.py # Run tests ``` ### Adding New Tools 1. Create tool file in appropriate directory (`api/` or `zerion/`) 2. Add brief description docstring 3. Implement using FastMCP decorator pattern 4. Update `__init__.py` exports 5. Add tests in `tests/` directory ## Contributing 1. Fork the repository 2. Create feature branch (`git checkout -b feature/amazing-feature`) 3. Commit changes (`git commit -m 'Add amazing feature'`) 4. Push to branch (`git push origin feature/amazing-feature`) 5. 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