Bridge Metrics MCP

1# Bridge Metrics MCP
2 
3An MCP server that provides real-time cross-chain bridge metrics, enabling AI agents to analyze liquidity, transaction flows, and performance across blockchain networks.
4 
5![GitHub License](https://img.shields.io/github/license/kukapay/bridge-metrics-mcp) 
6![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
7![Status](https://img.shields.io/badge/status-active-brightgreen.svg)
8 
9## Features
10 
11- **List Chains**: Retrieve a list of all chain slugs from DeFiLlama, sorted by Total Value Locked (TVL) in descending order.
12- **List Bridges**: Fetch all bridges, optionally including chain breakdowns, sorted by 24-hour volume.
13- **Historical Volumes**: Get historical volume data for a bridge or chain, with dates formatted as `YYYY-MM-DD HH:MM:SS`.
14- **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.
15- **Bridge Transactions**: Fetch transaction summaries for a specific bridge, with details like transaction hash, timestamp, and USD value.
16- **Prompts**: Includes example prompts for analyzing bridge volumes and comparing bridges based on metrics like weekly volume.
17 
18## Prerequisites
19 
20- **Python**: Version 3.10 or higher.
21- **uv**: Package and virtual environment manager for Python (recommended for dependency management).
22 
23## Installation
24 
251. **Clone the Repository**:
26   ```bash
27   git clone https://github.com/kukapay/bridge-metrics-mcp.git
28   cd bridge-metrics-mcp
29   ```
30 
312. **Install dependencies**:
32   ```bash
33   uv sync
34   ```
35 
363. **Install to Claude Desktop**:
37 
38    Install the server as a Claude Desktop application:
39    ```bash
40    uv run mcp install main.py --name "Bridge Metrics"
41    ```
42 
43    Configuration file as a reference:
44 
45    ```json
46    {
47       "mcpServers": {
48           "Bridge Metrics": {
49               "command": "uv",
50               "args": [ "--directory", "/path/to/bridge-metrics-mcp", "run", "main.py" ]
51           }
52       }
53    }
54    ```
55    Replace `/path/to/bridge-metrics-mcp` with your actual installation path.
56 
57 
58## Tools and Usage
59 
60The server provides the following tools, accessible via JSON-RPC or natural language prompts in compatible clients:
61 
621. **`list_chains`**:
63   - **Description**: Lists all chain slugs from DeFiLlama, sorted by TVL.
64   - **Parameters**: None.
65   - **Output**: Table with columns `Name`, `Gecko ID`, `Token Symbol`, `Chain ID`, `TVL`.
66 
672. **`list_bridges`**:
68   - **Description**: Lists all bridges, sorted by 24-hour volume, with optional chain inclusion.
69   - **Parameters**: `include_chains` (boolean, default `False`).
70   - **Output**: Table with columns `ID`, `Name`, `Display Name`, `Last 24h Volume`, `Chains`.
71 
723. **`get_historical_volumes`**:
73   - **Description**: Fetches historical volumes for a chain or bridge, with dates formatted as `YYYY-MM-DD HH:MM:SS`.
74   - **Parameters**: `chain` (string, required), `bridge_id` (integer, optional).
75   - **Output**: Table with columns `Date`, `Deposit USD`, `Withdraw USD`, `Deposit Txs`, `Withdraw Txs`.
76 
774. **`get_day_stats`**:
78   - **Description**: Retrieves 24-hour token volume breakdowns, sorted by deposit USD value.
79   - **Parameters**: `timestamp` (integer, required), `chain` (string, required), `bridge_id` (integer, optional).
80   - **Output**: Table with columns `Token ID`, `Symbol`, `Decimals`, `Deposit Amount`, `Deposit USD Value`, `Withdraw Amount`, `Withdraw USD Value`.
81 
825. **`get_transactions`**:
83   - **Description**: Fetches transaction summaries for a bridge, sorted by timestamp.
84   - **Parameters**: `bridge_id` (integer, required), `start_timestamp`, `end_timestamp`, `source_chain`, `address`, `limit` (all optional).
85   - **Output**: Table with columns `Tx Hash`, `Timestamp`, `Block`, `From`, `To`, `Token`, `Amount`, `Type`, `Chain`, `Bridge Name`, `USD Value`.
86 
876. **Prompts**:
88   - **`analyze_bridge_volume`**: Analyzes volume data for a specific bridge.
89   - **`compare_bridges`**: Compares two bridges based on a specified metric (e.g., `weeklyVolume`).
90 
91## Example Interactions
92 
93Below are example interactions using natural language prompts in a compatible MCP client, along with expected results.
94 
95### Example 1: Listing All Chains
96**Prompt**:
97```
98List all chains available on DeFiLlama.
99```
100 
101**Tool Called**: `list_chains`
102 
103**Result**:
104```
105+----------------+-------------+---------------+-----------+-------------+
106| Name           | Gecko ID    | Token Symbol  | Chain ID  | TVL         |
107+================+=============+===============+===========+=============+
108| Ethereum       | ethereum    | ETH           | 1         | 50000000000 |
109| Binance Smart  | binance-smart-chain | BNB   | 56        | 15000000000 |
110| Polygon        | polygon     | MATIC         | 137       | 5000000000  |
111+----------------+-------------+---------------+-----------+-------------+
112```
113 
114### Example 2: Listing Bridges with Chains
115**Prompt**:
116```
117Show all bridges with their supported chains, sorted by 24-hour volume.
118```
119 
120**Tool Called**: `list_bridges(include_chains=True)`
121 
122**Result**:
123```
124+----+-------------+---------------+-----------------+----------------------------------+
125| ID | Name        | Display Name  | Last 24h Volume | Chains                           |
126+====+=============+===============+=================+==================================+
127| 1  | polygon     | Polygon       | 1000000         | Ethereum, Polygon, Binance Smart |
128| 2  | optimism    | Optimism      | 750000          | Ethereum, Optimism               |
129| 3  | arbitrum    | Arbitrum      | 500000          | Ethereum, Arbitrum               |
130+----+-------------+---------------+-----------------+----------------------------------+
131```
132 
133### Example 3: Historical Volumes for a Chain
134**Prompt**:
135```
136Get historical volumes for the Ethereum chain.
137```
138 
139**Tool Called**: `get_historical_volumes(chain="ethereum")`
140 
141**Result**:
142```
143+---------------------+---------------+---------------+---------------+---------------+
144| Date                | Deposit USD   | Withdraw USD  | Deposit Txs   | Withdraw Txs  |
145+=====================+===============+===============+===============+===============+
146| 2025-09-12 00:00:00 | 1000000.0     | 500000.0      | 150           | 100           |
147| 2025-09-11 00:00:00 | 1200000.0     | 600000.0      | 180           | 120           |
148| 2025-09-10 00:00:00 | 900000.0      | 450000.0      | 130           | 90            |
149+---------------------+---------------+---------------+---------------+---------------+
150```
151 
152### Example 4: Daily Token Stats for a Bridge
153**Prompt**:
154```
155Show the 24-hour token stats for bridge ID 1 on Ethereum for September 12, 2025.
156```
157 
158**Tool Called**: `get_day_stats(timestamp=1752499200, chain="ethereum", bridge_id=1)`
159 
160**Result**:
161```
162+----------------+--------+----------+------------------+-------------------+------------------+-------------------+
163| Token ID       | Symbol | Decimals | Deposit Amount   | Deposit USD Value | Withdraw Amount  | Withdraw USD Value|
164+================+========+==========+==================+===================+==================+===================+
165| 0xa0b869...    | USDC   | 6        | 2000000          | 2000000.0         | 0                | 0.0               |
166| 0xc02aaa...    | ETH    | 18       | 1000000000000000 | 1500000.0         | 500000000000000  | 750000.0          |
167| 0xdac17f...    | DAI    | 18       | 0                | 0.0               | 1000000000000000 | 1000000.0         |
168+----------------+--------+----------+------------------+-------------------+------------------+-------------------+
169```
170 
171### Example 5: Analyzing Bridge Volume
172**Prompt**:
173```
174Analyze the volume data for the Polygon bridge using historical volumes.
175```
176 
177**Tool Called**: `get_historical_volumes(chain="polygon", bridge_id=1)`, followed by `analyze_bridge_volume`
178 
179**Result**:
180```
181Analyze the following volume data for the bridge 'Polygon':
182 
183+---------------------+---------------+---------------+---------------+---------------+
184| Date                | Deposit USD   | Withdraw USD  | Deposit Txs   | Withdraw Txs  |
185+=====================+===============+===============+===============+===============+
186| 2025-09-12 00:00:00 | 800000.0      | 400000.0      | 120           | 80            |
187| 2025-09-11 00:00:00 | 900000.0      | 450000.0      | 140           | 90            |
188| 2025-09-10 00:00:00 | 700000.0      | 350000.0      | 100           | 70            |
189+---------------------+---------------+---------------+---------------+---------------+
190 
191Key insights:
192- The Polygon bridge shows consistent deposit and withdrawal activity over the past three days.
193- Deposits are roughly double the withdrawals in USD value, indicating higher inflow than outflow.
194- Transaction counts are stable, with deposits averaging 120 transactions per day.
195```
196 
197## License
198 
199This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
200 
201