# Bridge Metrics MCP An MCP server that provides real-time cross-chain bridge metrics, enabling AI agents to analyze liquidity, transaction flows, and performance across blockchain networks. ![GitHub License](https://img.shields.io/github/license/kukapay/bridge-metrics-mcp) ![Python Version](https://img.shields.io/badge/python-3.10%2B-blue) ![Status](https://img.shields.io/badge/status-active-brightgreen.svg) ## Features - **List Chains**: Retrieve a list of all chain slugs from DeFiLlama, sorted by Total Value Locked (TVL) in descending order. - **List Bridges**: Fetch all bridges, optionally including chain breakdowns, sorted by 24-hour volume. - **Historical Volumes**: Get historical volume data for a bridge or chain, with dates formatted as `YYYY-MM-DD HH:MM:SS`. - **Daily Token Stats**: Retrieve 24-hour token volume breakdowns, including token ID, symbol, decimals, deposit/withdrawal amounts, and USD values, sorted by deposit USD value. - **Bridge Transactions**: Fetch transaction summaries for a specific bridge, with details like transaction hash, timestamp, and USD value. - **Prompts**: Includes example prompts for analyzing bridge volumes and comparing bridges based on metrics like weekly volume. ## Prerequisites - **Python**: Version 3.10 or higher. - **uv**: Package and virtual environment manager for Python (recommended for dependency management). ## Installation 1. **Clone the Repository**: ```bash git clone https://github.com/kukapay/bridge-metrics-mcp.git cd bridge-metrics-mcp ``` 2. **Install dependencies**: ```bash uv sync ``` 3. **Install to Claude Desktop**: Install the server as a Claude Desktop application: ```bash uv run mcp install main.py --name "Bridge Metrics" ``` Configuration file as a reference: ```json { "mcpServers": { "Bridge Metrics": { "command": "uv", "args": [ "--directory", "/path/to/bridge-metrics-mcp", "run", "main.py" ] } } } ``` Replace `/path/to/bridge-metrics-mcp` with your actual installation path. ## Tools and Usage The server provides the following tools, accessible via JSON-RPC or natural language prompts in compatible clients: 1. **`list_chains`**: - **Description**: Lists all chain slugs from DeFiLlama, sorted by TVL. - **Parameters**: None. - **Output**: Table with columns `Name`, `Gecko ID`, `Token Symbol`, `Chain ID`, `TVL`. 2. **`list_bridges`**: - **Description**: Lists all bridges, sorted by 24-hour volume, with optional chain inclusion. - **Parameters**: `include_chains` (boolean, default `False`). - **Output**: Table with columns `ID`, `Name`, `Display Name`, `Last 24h Volume`, `Chains`. 3. **`get_historical_volumes`**: - **Description**: Fetches historical volumes for a chain or bridge, with dates formatted as `YYYY-MM-DD HH:MM:SS`. - **Parameters**: `chain` (string, required), `bridge_id` (integer, optional). - **Output**: Table with columns `Date`, `Deposit USD`, `Withdraw USD`, `Deposit Txs`, `Withdraw Txs`. 4. **`get_day_stats`**: - **Description**: Retrieves 24-hour token volume breakdowns, sorted by deposit USD value. - **Parameters**: `timestamp` (integer, required), `chain` (string, required), `bridge_id` (integer, optional). - **Output**: Table with columns `Token ID`, `Symbol`, `Decimals`, `Deposit Amount`, `Deposit USD Value`, `Withdraw Amount`, `Withdraw USD Value`. 5. **`get_transactions`**: - **Description**: Fetches transaction summaries for a bridge, sorted by timestamp. - **Parameters**: `bridge_id` (integer, required), `start_timestamp`, `end_timestamp`, `source_chain`, `address`, `limit` (all optional). - **Output**: Table with columns `Tx Hash`, `Timestamp`, `Block`, `From`, `To`, `Token`, `Amount`, `Type`, `Chain`, `Bridge Name`, `USD Value`. 6. **Prompts**: - **`analyze_bridge_volume`**: Analyzes volume data for a specific bridge. - **`compare_bridges`**: Compares two bridges based on a specified metric (e.g., `weeklyVolume`). ## Example Interactions Below are example interactions using natural language prompts in a compatible MCP client, along with expected results. ### Example 1: Listing All Chains **Prompt**: ``` List all chains available on DeFiLlama. ``` **Tool Called**: `list_chains` **Result**: ``` +----------------+-------------+---------------+-----------+-------------+ | Name | Gecko ID | Token Symbol | Chain ID | TVL | +================+=============+===============+===========+=============+ | Ethereum | ethereum | ETH | 1 | 50000000000 | | Binance Smart | binance-smart-chain | BNB | 56 | 15000000000 | | Polygon | polygon | MATIC | 137 | 5000000000 | +----------------+-------------+---------------+-----------+-------------+ ``` ### Example 2: Listing Bridges with Chains **Prompt**: ``` Show all bridges with their supported chains, sorted by 24-hour volume. ``` **Tool Called**: `list_bridges(include_chains=True)` **Result**: ``` +----+-------------+---------------+-----------------+----------------------------------+ | ID | Name | Display Name | Last 24h Volume | Chains | +====+=============+===============+=================+==================================+ | 1 | polygon | Polygon | 1000000 | Ethereum, Polygon, Binance Smart | | 2 | optimism | Optimism | 750000 | Ethereum, Optimism | | 3 | arbitrum | Arbitrum | 500000 | Ethereum, Arbitrum | +----+-------------+---------------+-----------------+----------------------------------+ ``` ### Example 3: Historical Volumes for a Chain **Prompt**: ``` Get historical volumes for the Ethereum chain. ``` **Tool Called**: `get_historical_volumes(chain="ethereum")` **Result**: ``` +---------------------+---------------+---------------+---------------+---------------+ | Date | Deposit USD | Withdraw USD | Deposit Txs | Withdraw Txs | +=====================+===============+===============+===============+===============+ | 2025-09-12 00:00:00 | 1000000.0 | 500000.0 | 150 | 100 | | 2025-09-11 00:00:00 | 1200000.0 | 600000.0 | 180 | 120 | | 2025-09-10 00:00:00 | 900000.0 | 450000.0 | 130 | 90 | +---------------------+---------------+---------------+---------------+---------------+ ``` ### Example 4: Daily Token Stats for a Bridge **Prompt**: ``` Show the 24-hour token stats for bridge ID 1 on Ethereum for September 12, 2025. ``` **Tool Called**: `get_day_stats(timestamp=1752499200, chain="ethereum", bridge_id=1)` **Result**: ``` +----------------+--------+----------+------------------+-------------------+------------------+-------------------+ | Token ID | Symbol | Decimals | Deposit Amount | Deposit USD Value | Withdraw Amount | Withdraw USD Value| +================+========+==========+==================+===================+==================+===================+ | 0xa0b869... | USDC | 6 | 2000000 | 2000000.0 | 0 | 0.0 | | 0xc02aaa... | ETH | 18 | 1000000000000000 | 1500000.0 | 500000000000000 | 750000.0 | | 0xdac17f... | DAI | 18 | 0 | 0.0 | 1000000000000000 | 1000000.0 | +----------------+--------+----------+------------------+-------------------+------------------+-------------------+ ``` ### Example 5: Analyzing Bridge Volume **Prompt**: ``` Analyze the volume data for the Polygon bridge using historical volumes. ``` **Tool Called**: `get_historical_volumes(chain="polygon", bridge_id=1)`, followed by `analyze_bridge_volume` **Result**: ``` Analyze the following volume data for the bridge 'Polygon': +---------------------+---------------+---------------+---------------+---------------+ | Date | Deposit USD | Withdraw USD | Deposit Txs | Withdraw Txs | +=====================+===============+===============+===============+===============+ | 2025-09-12 00:00:00 | 800000.0 | 400000.0 | 120 | 80 | | 2025-09-11 00:00:00 | 900000.0 | 450000.0 | 140 | 90 | | 2025-09-10 00:00:00 | 700000.0 | 350000.0 | 100 | 70 | +---------------------+---------------+---------------+---------------+---------------+ Key insights: - The Polygon bridge shows consistent deposit and withdrawal activity over the past three days. - Deposits are roughly double the withdrawals in USD value, indicating higher inflow than outflow. - Transaction counts are stable, with deposits averaging 120 transactions per day. ``` ## License This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.