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 !Python Version !Status

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

Clone the Repository:

   git clone https://github.com/kukapay/bridge-metrics-mcp.git
   cd bridge-metrics-mcp

Install dependencies:

   uv sync

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:

    {
       "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:

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.

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.

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.

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.

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.

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)

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.

bridge-metrics-mcp