kukapay/dex-pools-mcp

An MCP server that provides AI agents with real-time access to DEX liquidity pool data, enabling smarter trading, analytics, and automated strategies.

Features

• Query Supported Networks: Retrieve a list of supported blockchain networks on GeckoTerminal.
• Query Supported DEXes: Fetch DEXes available on a specific network.
• Fetch New Pools: List the latest pools across all networks or a specific network, with details like DEX, network, name, base price, reserve, volume, and address.
• Fetch Trending Pools: Retrieve trending pools across all networks or a specific network, sorted by duration (5m, 1h, 6h, 24h).
• Fetch Top Pools: Get top pools for a specific network or DEX, sorted by transaction count or volume.
• Search Pools: Search for pools on a specific network using a query term (e.g., token name or symbol).

Prerequisites

• Python 3.10 or higher
• uv: Package and virtual environment manager for Python (recommended for dependency management).
• A CoinGecko Demo API key (obtainable from coingecko.com)

Installation

1. Clone the Repository:

   git clone https://github.com/kukapay/dex-pools-mcp.git
   cd dex-pools-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 "DEX Pools"
   

   Configuration file as a reference:

   {
      "mcpServers": {
          "DEX Pools": {
              "command": "uv",
              "args": [ "--directory", "/path/to/dex-pools-mcp", "run", "main.py" ],
              "env": { "COINGECKO_API_KEY": "coingecko_api_key"}
          }
      }
   }
   

   Replace /path/to/dex-pools-mcp with your actual installation path, and replace coingecko_api_key with your API key from CoinGecko.

Usage

Available Tools

The server provides the following tools, accessible via MCP clients (e.g., Claude Desktop) or the MCP Inspector:

• get_supported_networks(page: int = 1): Returns a table of supported network IDs and names.
• get_supported_dexes_by_network(network: str = "eth", page: int = 1): Returns a table of DEX IDs and names for a given network.
• get_new_pools(page: int = 1, include: str = "base_token,quote_token,dex,network"): Returns a table of new pools across all networks with columns: DEX, Network, Name, Base Price (USD), Reserve (USD), Volume 24h (USD), Address.
• get_new_pools_by_network(network: str = "eth", page: int = 1, include: str = "base_token,quote_token,dex,network"): Returns a table of new pools for a specific network with columns: DEX, Name, Base Price in Quote, Reserve (USD), Volume 24h (USD), Address.
• get_trending_pools(page: int = 1, duration: str = "24h", include: str = "base_token,quote_token,dex,network"): Returns a table of trending pools across all networks with columns: DEX, Network, Name, Base Price in Quote, Reserve (USD), Volume 24h (USD), Address.
• get_trending_pools_by_network(network: str = "eth", page: int = 1, duration: str = "24h", include: str = "base_token,quote_token,dex"): Returns a table of trending pools for a specific network.
• get_top_pools_by_network(network: str = "eth", page: int = 1, sort: str = "h24_tx_count_desc", include: str = "base_token,quote_token,dex"): Returns a table of top pools for a specific network.
• get_top_pools_by_dex(network: str = "eth", dex: str = "sushiswap", page: int = 1, sort: str = "h24_tx_count_desc", include: str = "base_token,quote_token,dex"): Returns a table of top pools for a specific DEX on a network.
• search_pools(query: str = "weth", network: str = "eth", page: int = 1, include: str = "base_token,quote_token,dex"): Returns a table of pools matching a search query on a specific network.

Examples

Below are examples for each tool, including a natural language prompt and the expected output (mock data for illustration).

1. get_supported_networks

Prompt: "List the supported blockchain networks on GeckoTerminal for page 1."

Output:

+----------+-----------------+
| ID       | Name            |
+==========+=================+
| eth      | Ethereum        |
+----------+-----------------+
| bsc      | BNB Chain       |
+----------+-----------------+
| polygon  | Polygon         |
+----------+-----------------+

2. get_supported_dexes_by_network

Prompt: "Show me the DEXes available on the Ethereum network for page 1."

Output:

+--------------+-----------------+
| ID           | Name            |
+==============+=================+
| uniswap_v3   | Uniswap V3      |
+--------------+-----------------+
| sushiswap    | SushiSwap       |
+--------------+-----------------+
| pancakeswap  | PancakeSwap     |
+--------------+-----------------+

3. get_new_pools

Prompt: "Get the latest pools across all networks for page 1."

Output:

+--------------+----------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
| DEX          | Network  | Name              | Base Price (USD) | Reserve (USD) | Volume 24h (USD)  | Address                                     |
+==============+==========+===================+==================+===============+===================+=============================================+
| uniswap_v3   | eth      | WETH / USDC 0.05% | 3653.12          | 163988541.38  | 536545444.90      | 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640 |
+--------------+----------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
| sushiswap    | bsc      | BNB / USDT        | 582.45           | 9876543.21    | 12345678.90       | 0x1234567890abcdef1234567890abcdef12345678 |
+--------------+----------+-------------------+------------------+---------------+-------------------+---------------------------------------------+

4. get_new_pools_by_network

Prompt: "List the latest pools on the Ethereum network for page 1."

Output:

+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
| DEX          | Name              | Base Price       | Reserve (USD) | Volume 24h (USD)  | Address                                     |
+==============+===================+==================+===============+===================+=============================================+
| uniswap_v3   | WETH / USDC 0.05% | 3662.46          | 163988541.38  | 536545444.90      | 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640 |
+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
| sushiswap    | WETH / DAI        | 3650.00          | 8765432.10    | 9876543.21        | 0xabcdef1234567890abcdef1234567890abcdef12 |
+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+

5. get_trending_pools

Prompt: "Show trending pools across all networks for the last 24 hours on page 1."

Output:

+--------------+----------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
| DEX          | Network  | Name              | Base Price       | Reserve (USD) | Volume 24h (USD)  | Address                                     |
+==============+==========+===================+==================+===============+===================+=============================================+
| uniswap_v3   | eth      | WETH / USDC 0.05% | 3662.46          | 163988541.38  | 536545444.90      | 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640 |
+--------------+----------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
| pancakeswap  | bsc      | CAKE / BNB        | 2.34             | 5432109.87    | 8765432.10        | 0x7890abcdef1234567890abcdef1234567890abcd |
+--------------+----------+-------------------+------------------+---------------+-------------------+---------------------------------------------+

6. get_trending_pools_by_network

Prompt: "Get trending pools on the Ethereum network for the last 24 hours on page 1."

Output:

+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
| DEX          | Name              | Base Price       | Reserve (USD) | Volume 24h (USD)  | Address                                     |
+==============+===================+==================+===============+===================+=============================================+
| uniswap_v3   | WETH / USDC 0.05% | 3662.46          | 163988541.38  | 536545444.90      | 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640 |
+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
| sushiswap    | WETH / DAI        | 3650.00          | 8765432.10    | 9876543.21        | 0xabcdef1234567890abcdef1234567890abcdef12 |
+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+

7. get_top_pools_by_network

Prompt: "List the top pools on the Ethereum network sorted by transaction count for page 1."

Output:

+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
| DEX          | Name              | Base Price       | Reserve (USD) | Volume 24h (USD)  | Address                                     |
+==============+===================+==================+===============+===================+=============================================+
| uniswap_v3   | WETH / USDC 0.05% | 3662.46          | 163988541.38  | 536545444.90      | 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640 |
+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
| sushiswap    | WETH / DAI        | 3650.00          | 8765432.10    | 9876543.21        | 0xabcdef1234567890abcdef1234567890abcdef12 |
+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+

8. get_top_pools_by_dex

Prompt: "Show the top pools on SushiSwap for the Ethereum network, sorted by transaction count for page 1."

Output:

+-------------------+------------------+---------------+-------------------+---------------------------------------------+
| Name              | Base Price       | Reserve (USD) | Volume 24h (USD)  | Address                                     |
+===================+==================+===============+===================+=============================================+
| WETH / DAI        | 3650.00          | 8765432.10    | 9876543.21        | 0xabcdef1234567890abcdef1234567890abcdef12 |
+-------------------+------------------+---------------+-------------------+---------------------------------------------+
| SUSHI / WETH      | 1.23             | 4321098.76    | 5432109.87        | 0x1234567890abcdef1234567890abcdef12345678 |
+-------------------+------------------+---------------+-------------------+---------------------------------------------+

9. search_pools

Prompt: "Search for pools with 'WETH' on the Ethereum network for page 1."

Output:

+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
| DEX          | Name              | Base Price       | Reserve (USD) | Volume 24h (USD)  | Address                                     |
+==============+===================+==================+===============+===================+=============================================+
| uniswap_v3   | WETH / USDC 0.05% | 3662.46          | 163988541.38  | 536545444.90      | 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640 |
+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
| sushiswap    | WETH / DAI        | 3650.00          | 8765432.10    | 9876543.21        | 0xabcdef1234567890abcdef1234567890abcdef12 |
+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+

License

This project is licensed under the MIT License. See the LICENSE file for details.