DEX Pools MCP

1# DEX Pools MCP
2 
3An MCP server that provides AI agents with real-time access to DEX liquidity pool data, enabling smarter trading, analytics, and automated strategies.
4 
5![GitHub License](https://img.shields.io/github/license/kukapay/dex-pools-mcp) 
6![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
7![Status](https://img.shields.io/badge/status-active-brightgreen.svg)
8 
9## Features
10 
11- **Query Supported Networks**: Retrieve a list of supported blockchain networks on GeckoTerminal.
12- **Query Supported DEXes**: Fetch DEXes available on a specific network.
13- **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.
14- **Fetch Trending Pools**: Retrieve trending pools across all networks or a specific network, sorted by duration (5m, 1h, 6h, 24h).
15- **Fetch Top Pools**: Get top pools for a specific network or DEX, sorted by transaction count or volume.
16- **Search Pools**: Search for pools on a specific network using a query term (e.g., token name or symbol).
17 
18## Prerequisites
19 
20- Python 3.10 or higher
21- **uv**: Package and virtual environment manager for Python (recommended for dependency management).
22- A CoinGecko Demo API key (obtainable from [coingecko.com](https://www.coingecko.com/))
23 
24## Installation
25 
261. **Clone the Repository**:
27   ```bash
28   git clone https://github.com/kukapay/dex-pools-mcp.git
29   cd dex-pools-mcp
30   ```
31 
322. Install dependencies:
33   ```bash
34   uv sync
35   ```
36 
373. Install to Claude Desktop:
38 
39   Install the server as a Claude Desktop application:
40   ```bash
41   uv run mcp install main.py --name "DEX Pools"
42   ```
43 
44   Configuration file as a reference:
45 
46   ```json
47   {
48      "mcpServers": {
49          "DEX Pools": {
50              "command": "uv",
51              "args": [ "--directory", "/path/to/dex-pools-mcp", "run", "main.py" ],
52              "env": { "COINGECKO_API_KEY": "coingecko_api_key"}
53          }
54      }
55   }
56   ```
57   Replace `/path/to/dex-pools-mcp` with your actual installation path, and replace `coingecko_api_key` with your API key from CoinGecko.
58 
59## Usage
60 
61### Available Tools
62 
63The server provides the following tools, accessible via MCP clients (e.g., Claude Desktop) or the MCP Inspector:
64- `get_supported_networks(page: int = 1)`: Returns a table of supported network IDs and names.
65- `get_supported_dexes_by_network(network: str = "eth", page: int = 1)`: Returns a table of DEX IDs and names for a given network.
66- `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.
67- `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.
68- `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.
69- `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.
70- `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.
71- `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.
72- `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.
73 
74### Examples
75 
76Below are examples for each tool, including a natural language prompt and the expected output (mock data for illustration).
77 
78#### 1. `get_supported_networks`
79**Prompt**: "List the supported blockchain networks on GeckoTerminal for page 1."
80 
81**Output**:
82```
83+----------+-----------------+
84| ID       | Name            |
85+==========+=================+
86| eth      | Ethereum        |
87+----------+-----------------+
88| bsc      | BNB Chain       |
89+----------+-----------------+
90| polygon  | Polygon         |
91+----------+-----------------+
92```
93 
94#### 2. `get_supported_dexes_by_network`
95**Prompt**: "Show me the DEXes available on the Ethereum network for page 1."
96 
97**Output**:
98```
99+--------------+-----------------+
100| ID           | Name            |
101+==============+=================+
102| uniswap_v3   | Uniswap V3      |
103+--------------+-----------------+
104| sushiswap    | SushiSwap       |
105+--------------+-----------------+
106| pancakeswap  | PancakeSwap     |
107+--------------+-----------------+
108```
109 
110#### 3. `get_new_pools`
111**Prompt**: "Get the latest pools across all networks for page 1."
112 
113**Output**:
114```
115+--------------+----------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
116| DEX          | Network  | Name              | Base Price (USD) | Reserve (USD) | Volume 24h (USD)  | Address                                     |
117+==============+==========+===================+==================+===============+===================+=============================================+
118| uniswap_v3   | eth      | WETH / USDC 0.05% | 3653.12          | 163988541.38  | 536545444.90      | 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640 |
119+--------------+----------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
120| sushiswap    | bsc      | BNB / USDT        | 582.45           | 9876543.21    | 12345678.90       | 0x1234567890abcdef1234567890abcdef12345678 |
121+--------------+----------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
122```
123 
124#### 4. `get_new_pools_by_network`
125**Prompt**: "List the latest pools on the Ethereum network for page 1."
126 
127**Output**:
128```
129+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
130| DEX          | Name              | Base Price       | Reserve (USD) | Volume 24h (USD)  | Address                                     |
131+==============+===================+==================+===============+===================+=============================================+
132| uniswap_v3   | WETH / USDC 0.05% | 3662.46          | 163988541.38  | 536545444.90      | 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640 |
133+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
134| sushiswap    | WETH / DAI        | 3650.00          | 8765432.10    | 9876543.21        | 0xabcdef1234567890abcdef1234567890abcdef12 |
135+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
136```
137 
138#### 5. `get_trending_pools`
139**Prompt**: "Show trending pools across all networks for the last 24 hours on page 1."
140 
141**Output**:
142```
143+--------------+----------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
144| DEX          | Network  | Name              | Base Price       | Reserve (USD) | Volume 24h (USD)  | Address                                     |
145+==============+==========+===================+==================+===============+===================+=============================================+
146| uniswap_v3   | eth      | WETH / USDC 0.05% | 3662.46          | 163988541.38  | 536545444.90      | 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640 |
147+--------------+----------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
148| pancakeswap  | bsc      | CAKE / BNB        | 2.34             | 5432109.87    | 8765432.10        | 0x7890abcdef1234567890abcdef1234567890abcd |
149+--------------+----------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
150```
151 
152#### 6. `get_trending_pools_by_network`
153**Prompt**: "Get trending pools on the Ethereum network for the last 24 hours on page 1."
154 
155**Output**:
156```
157+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
158| DEX          | Name              | Base Price       | Reserve (USD) | Volume 24h (USD)  | Address                                     |
159+==============+===================+==================+===============+===================+=============================================+
160| uniswap_v3   | WETH / USDC 0.05% | 3662.46          | 163988541.38  | 536545444.90      | 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640 |
161+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
162| sushiswap    | WETH / DAI        | 3650.00          | 8765432.10    | 9876543.21        | 0xabcdef1234567890abcdef1234567890abcdef12 |
163+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
164```
165 
166#### 7. `get_top_pools_by_network`
167**Prompt**: "List the top pools on the Ethereum network sorted by transaction count for page 1."
168 
169**Output**:
170```
171+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
172| DEX          | Name              | Base Price       | Reserve (USD) | Volume 24h (USD)  | Address                                     |
173+==============+===================+==================+===============+===================+=============================================+
174| uniswap_v3   | WETH / USDC 0.05% | 3662.46          | 163988541.38  | 536545444.90      | 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640 |
175+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
176| sushiswap    | WETH / DAI        | 3650.00          | 8765432.10    | 9876543.21        | 0xabcdef1234567890abcdef1234567890abcdef12 |
177+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
178```
179 
180#### 8. `get_top_pools_by_dex`
181**Prompt**: "Show the top pools on SushiSwap for the Ethereum network, sorted by transaction count for page 1."
182 
183**Output**:
184```
185+-------------------+------------------+---------------+-------------------+---------------------------------------------+
186| Name              | Base Price       | Reserve (USD) | Volume 24h (USD)  | Address                                     |
187+===================+==================+===============+===================+=============================================+
188| WETH / DAI        | 3650.00          | 8765432.10    | 9876543.21        | 0xabcdef1234567890abcdef1234567890abcdef12 |
189+-------------------+------------------+---------------+-------------------+---------------------------------------------+
190| SUSHI / WETH      | 1.23             | 4321098.76    | 5432109.87        | 0x1234567890abcdef1234567890abcdef12345678 |
191+-------------------+------------------+---------------+-------------------+---------------------------------------------+
192```
193 
194#### 9. `search_pools`
195**Prompt**: "Search for pools with 'WETH' on the Ethereum network for page 1."
196 
197**Output**:
198```
199+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
200| DEX          | Name              | Base Price       | Reserve (USD) | Volume 24h (USD)  | Address                                     |
201+==============+===================+==================+===============+===================+=============================================+
202| uniswap_v3   | WETH / USDC 0.05% | 3662.46          | 163988541.38  | 536545444.90      | 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640 |
203+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
204| sushiswap    | WETH / DAI        | 3650.00          | 8765432.10    | 9876543.21        | 0xabcdef1234567890abcdef1234567890abcdef12 |
205+--------------+-------------------+------------------+---------------+-------------------+---------------------------------------------+
206```
207 
208## License
209 
210This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
211 
212