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

![GitHub License](https://img.shields.io/github/license/kukapay/dex-pools-mcp) 
![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
![Status](https://img.shields.io/badge/status-active-brightgreen.svg)

## 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](https://www.coingecko.com/))

## Installation

1. **Clone the Repository**:
   ```bash
   git clone https://github.com/kukapay/dex-pools-mcp.git
   cd dex-pools-mcp
   ```

2. Install dependencies:
   ```bash
   uv sync
   ```

3. Install to Claude Desktop:

   Install the server as a Claude Desktop application:
   ```bash
   uv run mcp install main.py --name "DEX Pools"
   ```

   Configuration file as a reference:

   ```json
   {
      "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](LICENSE) file for details.