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