README.md•7.18 kB
# Wormhole Metrics MCP
An MCP server that analyzes cross-chain activity on the Wormhole protocol, providing insights into transaction volumes, top assets, source-destination chain pairs, and key performance indicators (KPIs).
## Features
- **Comprehensive Tools**: Includes tools for cross-chain activity, money flow, top assets, chain pairs, symbols, token corridors, and KPIs.
- **Markdown Output**: Returns data as Markdown-formatted tables for clear presentation.
## Installation
### Prerequisites
- Python 3.10 or higher
- [uv](https://github.com/astral-sh/uv) (recommended package manager)
### Setup
1. **Clone the Repository**
```bash
git clone https://github.com/kukapay/wormhole-metrics-mcp.git
cd wormhole-metrics-mcp
```
2. **Install Dependencies**
```bash
uv sync
```
3. **Installing to Claude Desktop**:
Install the server as a Claude Desktop application:
```bash
uv run mcp install main.py --name "Wormhole Metrics"
```
Configuration file as a reference:
```json
{
"mcpServers": {
"Wormhole Metrics": {
"command": "uv",
"args": [ "--directory", "/path/to/wormhole-metrics-mcp", "run", "main.py" ]
}
}
}
```
Replace `/path/to/wormhole-metrics-mcp` with your actual installation path.
## Usage
The `wormhole-metrics-mcp` server exposes several tools via the MCP interface. Below is an overview of the tools and their usage.
### Tools
1. **get_cross_chain_activity**
- **Description**: Fetches cross-chain activity data, returning a pivot table of volumes between source and destination chains.
- **Parameters**:
- `timeSpan`: `7d`, `30d`, `90d`, `1y`, `all-time` (default: `7d`)
- `by`: `notional`, `tx count` (default: `notional`)
- `app`: Comma-separated list of apps (default: empty)
- **Example**:
- **Prompt**: "Show me the cross-chain activity for the last 7 days, measured by notional volume."
- **Output**:
```markdown
| source_chain | Solana | Ethereum | Base |
|--------------|--------|---------|------------|
| Mantle | 23.545 | | |
| Polygon | | 245951 | 747048 |
```
2. **get_money_flow**
- **Description**: Retrieves transaction count and volume data for a specific period.
- **Parameters**:
- `timespan`: `1h`, `1d`, `1mo`, `1y` (default: `1d`)
- `from_date`: ISO 8601 format (e.g., `2024-01-01T15:04:05Z`, default: empty)
- `to_date`: ISO 8601 format (default: empty)
- `appId`: Application ID (default: empty)
- `sourceChain`: Source chain ID (default: empty)
- `targetChain`: Target chain ID (default: empty)
- **Example**:
- **Prompt**: "Get the transaction count and volume for Solana as the source chain over the last day."
- **Output**:
```markdown
| from | to | source_chain | volume | count |
|----------------------|----------------------|--------------|-------------------|-------|
| 2025-01-01T00:00:00Z | 2025-01-02T00:00:00Z | Solana | 346085661921482 | 550 |
| 2025-01-02T00:00:00Z | 2025-01-03T00:00:00Z | Solana | 1915450117554795 | 747 |
```
3. **get_top_assets_by_volume**
- **Description**: Lists top assets by volume, including emitter and token chains.
- **Parameters**:
- `timeSpan`: `7d`, `15d`, `30d` (default: `7d`)
- **Example**:
- **Prompt**: "List the top assets by volume for the past 15 days."
- **Output**:
```markdown
| emitter_chain | symbol | token_chain | token_address | volume |
|---------------|--------|-------------|------------------------------------------|----------------|
| Solana | WBTC | Ethereum | 0000000000000000000000002260fac5e5542a773aa44fbcfedf7c193bc2c599 | 25101807.78824 |
| Ethereum | RNDR | Ethereum | 0000000000000000000000006de037ef9ad2725eb40118bb1702ebb27e4aeb24 | 9829032.688 |
```
4. **get_top_chain_pairs_by_num_transfers**
- **Description**: Returns top chain pairs by number of transfers.
- **Parameters**:
- `timeSpan`: `7d`, `15d`, `30d` (default: `7d`)
- **Example**:
- **Prompt**: "Show the top chain pairs by number of transfers for the last 7 days."
- **Output**:
```markdown
| source_chain | destination_chain | number_of_transfers |
|--------------|-------------------|---------------------|
| Optimism | Solana | 2849 |
| Ethereum | Solana | 2466 |
| Base | Arbitrum | 1993 |
```
5. **get_top_symbols_by_volume**
- **Description**: Fetches top symbols by volume and transaction count.
- **Parameters**:
- `timeSpan`: `7d`, `15d`, `30d` (default: `7d`)
- **Example**:
- **Prompt**: "What are the top symbols by volume over the last 30 days?"
- **Output**:
```markdown
| symbol | volume | txs |
|--------|-----------------|-----|
| WBTC | 28434555.496489 | 133 |
| RNDR | 9829032.688 | 49 |
| WETH | 9662352.854166 | 60 |
```
6. **get_top100_corridors**
- **Description**: Lists top 100 token corridors by number of transactions.
- **Parameters**:
- `timeSpan`: `2d`, `7d` (default: `2d`)
- **Example**:
- **Prompt**: "Get the top 100 token corridors by transactions for the last 7 days."
- **Output**:
```markdown
| source_chain | target_chain | token_chain | token_address | txs |
|--------------|--------------|-------------|------------------------------------------|-----|
| Optimism | Solana | Optimism | 000000000000000000000000ef4461891dfb3ac8572ccf7c794664a8dd927945 | 2777|
| Base | Arbitrum | Base | 000000000000000000000000271cdba25be9be2e024bc0a550012b2e5934420e | 1892|
```
7. **get_kpi_list**
- **Description**: Retrieves key performance indicators (KPIs) for the Wormhole protocol.
- **Parameters**: None
- **Example**:
- **Prompt**: "Show me the key performance indicators for Wormhole."
- **Output**:
```markdown
| 24h_messages | total_messages | total_tx_count | total_volume | tvl | 24h_volume | 7d_volume | 30d_volume |
|--------------|----------------|----------------|--------------------|-------------|--------------|--------------|---------------|
| 192987 | 1111114235 | 6023755 | 60718344331.570806 | 2582546224 | 22688586.172 | 252786937.009| 1349155202.545|
```
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.