kukapay/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.

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:

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

2. Install dependencies:

   uv sync
   

3. Install to Claude Desktop:

   Install the server as a Claude Desktop application:

   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:

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 file for details.