Uniswap PoolSpy MCP Server

1# Uniswap PoolSpy MCP Server
2 
3An MCP server that tracks newly created liquidity pools on Uniswap across nine blockchain networks — Ethereum, Base, Optimism, Arbitrum, Polygon, BNB Smart Chain (BSC), Avalanche, Celo, and Blast — providing real-time data for DeFi analysts, traders, and developers.
4 
5![Python](https://img.shields.io/badge/python-3.10+-blue.svg)
6![License](https://img.shields.io/badge/license-MIT-green.svg)
7![Status](https://img.shields.io/badge/status-active-brightgreen.svg)
8 
9## Features
10 
11- Monitors Uniswap V3 pool creation across 9 blockchain networks.
12- Customizable time range and result limits for querying new pools.
13- Supports sorting by timestamp, transaction count, volume, or TVL.
14 
15## Prerequisites
16 
17- Python 3.10 or higher
18- [uv](https://github.com/astral-sh/uv) for package management
19- A valid [The Graph API key](https://thegraph.com/studio/apikeys/)
20- MCP-compatible environment (e.g., Claude Desktop) for full functionality
21 
22## Installation
23 
241. **Clone the Repository**:
25   ```bash
26   git clone https://github.com/yourusername/uniswap-poolspy-mcp.git
27   cd uniswap-poolspy-mcp
28   ```
29 
302. **Set Up Environment**:
31   Install `uv` if you haven't already:
32   ```bash
33   curl -LsSf https://astral.sh/uv/install.sh | sh
34   ```
35 
363. **Install Dependencies**:
37   Use `uv` to sync dependencies from `pyproject.toml`:
38   ```bash
39   uv sync
40   ```
41 
424. **Configure API Key**:
43   Create a `.env` file in the project root:
44   ```bash
45   echo "THEGRAPH_API_KEY=your-api-key-here" > .env
46   ```
47   Replace `your-api-key-here` with your actual The Graph API key.
48 
49## Usage
50 
51### Running the Server
52 
53Start the MCP server:
54```bash
55uv run main.py
56```
57 
58For development with MCP Inspector:
59```bash
60uv run mcp dev main.py
61```
62 
63### Integrating with Claude Desktop
64 
65Install the server as an MCP plugin:
66```bash
67uv run mcp install main.py --name "UniswapPoolSpy"
68```
69 
70### Configuration
71 
72To make the server discoverable by MCP clients (e.g., Claude Desktop), configure it in an `mcpServers` file:
73 
74```json
75{
76  "mcpServers": {
77    "Uniswap-PoolSpy": {
78      "command": "uv",
79      "args": ["--directory", "path/to/uniswap-poolspy-mcp", "run", "main.py"],
80      "env": {
81        "THEGRAPH_API_KEY": "your api key from The Graph"
82      }
83    }
84  }
85}
86   ```
87 
88 
89### Querying New Pools
90 
91Use the `get_new_pools` tool in Claude Desktop with natural language queries like:
92- "Show me new pools on Ethereum from the last 10 minutes"
93- "List pools on Base sorted by volume, limit to 50"
94- "What pools were created on Polygon in the past hour, ordered by TVL?"
95 
96The tool accepts these parameters:
97- `chain`: Blockchain network (e.g., "ethereum", "base", "optimism")
98- `order_by`: Sort field ("timestamp", "txcount", "volume", "tvl")
99- `time_range_seconds`: Lookback period in seconds (default: 300)
100- `limit`: Maximum number of pools to return (default: 100)
101 
102### Example Output
103```
104Newly Created Trading Pools (Last 5 Minutes, Limit: 100):
105Pool Address: 0x1234...abcd
106Tokens: WETH/USDC
107Created At: 2025-03-18 12:34:56
108Block Number: 12345678
109Transaction Count: 5
110Volume (USD): 15000.25
111Total Value Locked (USD): 50000.75
112 
113Pool Address: 0x5678...efgh
114Tokens: DAI/USDT
115Created At: 2025-03-18 12:33:45
116Block Number: 12345670
117Transaction Count: 3
118Volume (USD): 8000.50
119Total Value Locked (USD): 25000.00
120```
121 
122## Supported Chains
123 
124- Ethereum
125- Base
126- Optimism
127- Arbitrum
128- Polygon
129- BNB Smart Chain (BSC)
130- Avalanche
131- Celo
132- Blast
133 
134## License
135 
136This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
137 
138