README - wormhole-metrics-mcp by kukapay

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