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).

GitHub License

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 (recommended package manager)

Setup

Clone the Repository

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

Install Dependencies
```
uv sync
```

Installing to Claude Desktop:

Install the server as a Claude Desktop application:

uv run mcp install main.py --name "Wormhole Metrics"

Configuration file as a reference:

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

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:
```
| source_chain | Solana | Ethereum | Base       |
|--------------|--------|---------|------------|
| Mantle       | 23.545 |         |            |
| Polygon      |        | 245951  | 747048     |
```
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:
```
| 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   |
```

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:

| emitter_chain | symbol | token_chain | token_address                            | volume         |
|---------------|--------|-------------|------------------------------------------|----------------|
| Solana        | WBTC   | Ethereum    | 0000000000000000000000002260fac5e5542a773aa44fbcfedf7c193bc2c599 | 25101807.78824 |
| Ethereum      | RNDR   | Ethereum    | 0000000000000000000000006de037ef9ad2725eb40118bb1702ebb27e4aeb24 | 9829032.688    |

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:

| source_chain | destination_chain | number_of_transfers |
|--------------|-------------------|---------------------|
| Optimism     | Solana            | 2849                |
| Ethereum     | Solana            | 2466                |
| Base         | Arbitrum          | 1993                |

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:
```
| symbol | volume          | txs |
|--------|-----------------|-----|
| WBTC   | 28434555.496489 | 133 |
| RNDR   | 9829032.688     | 49  |
| WETH   | 9662352.854166  | 60  |
```

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:

| source_chain | target_chain | token_chain | token_address                            | txs |
|--------------|--------------|-------------|------------------------------------------|-----|
| Optimism     | Solana       | Optimism    | 000000000000000000000000ef4461891dfb3ac8572ccf7c794664a8dd927945 | 2777|
| Base         | Arbitrum     | Base        | 000000000000000000000000271cdba25be9be2e024bc0a550012b2e5934420e | 1892|

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:

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

Installation

Prerequisites

Python 3.10 or higher

uv (recommended package manager)

Setup

Clone the Repository

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

Install Dependencies

uv sync

Installing to Claude Desktop:

Install the server as a Claude Desktop application:

uv run mcp install main.py --name "Wormhole Metrics"

Configuration file as a reference:

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

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:

| source_chain | Solana | Ethereum | Base       |
|--------------|--------|---------|------------|
| Mantle       | 23.545 |         |            |
| Polygon      |        | 245951  | 747048     |

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:

| 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   |

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:

| emitter_chain | symbol | token_chain | token_address                            | volume         |
|---------------|--------|-------------|------------------------------------------|----------------|
| Solana        | WBTC   | Ethereum    | 0000000000000000000000002260fac5e5542a773aa44fbcfedf7c193bc2c599 | 25101807.78824 |
| Ethereum      | RNDR   | Ethereum    | 0000000000000000000000006de037ef9ad2725eb40118bb1702ebb27e4aeb24 | 9829032.688    |

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:

| source_chain | destination_chain | number_of_transfers |
|--------------|-------------------|---------------------|
| Optimism     | Solana            | 2849                |
| Ethereum     | Solana            | 2466                |
| Base         | Arbitrum          | 1993                |

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:

| symbol | volume          | txs |
|--------|-----------------|-----|
| WBTC   | 28434555.496489 | 133 |
| RNDR   | 9829032.688     | 49  |
| WETH   | 9662352.854166  | 60  |

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:

| source_chain | target_chain | token_chain | token_address                            | txs |
|--------------|--------------|-------------|------------------------------------------|-----|
| Optimism     | Solana       | Optimism    | 000000000000000000000000ef4461891dfb3ac8572ccf7c794664a8dd927945 | 2777|
| Base         | Arbitrum     | Base        | 000000000000000000000000271cdba25be9be2e024bc0a550012b2e5934420e | 1892|

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:

| 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|