Dune Analytics MCP Server

# mcp-server-dune A Model Context Protocol (MCP) server for integrating AI agents with [Dune Analytics](https://dune.com) blockchain data. ## Requirements - Python 3.11+ - Dune Analytics API key ## Features ### Tools - **run_query** - Execute saved Dune queries and wait for results - **submit_query** - Submit queries asynchronously for long-running jobs - **get_execution_status** - Check the status of running queries - **get_execution_results** - Retrieve results from completed executions - **run_sql** - Execute raw ad-hoc DuneSQL queries - **create_query** - Save new queries to your Dune library - **update_query** - Modify existing queries - **archive_query** - Archive queries from active workspace ### Resources (dune:// scheme) - `dune://query/{id}/latest` - Cached results (zero credits) - `dune://query/{id}/sql` - Query SQL definition - `dune://execution/{id}/status` - Execution job status ### Prompts - **generate_dune_sql** - Guide for writing valid DuneSQL - **analyze_result** - Guide for interpreting query results ## Installation ```bash # Install from source pip install -e . # Or install dependencies directly pip install fastmcp>=2.0.0 dune-client>=1.10.0 pydantic>=2.0.0 ``` ## Configuration Set your Dune API key as an environment variable: ```bash # Linux/macOS export DUNE_API_KEY="your-api-key-here" # Windows Command Prompt set DUNE_API_KEY=your-api-key-here # Windows PowerShell $env:DUNE_API_KEY="your-api-key-here" ``` ### Claude Desktop Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "dune": { "command": "python", "args": ["-m", "mcp_server_dune"], "env": { "DUNE_API_KEY": "your-api-key-here" } } } } ``` ### Direct Execution ```bash # Run the server python -m mcp_server_dune ``` ## Usage Examples ### Execute a Saved Query ```python # Run query ID 123456 with parameters run_query( query_id=123456, params={"token_address": "0x..."}, performance="medium", limit=50 ) ``` ### Execute Ad-Hoc SQL ```python # Run raw DuneSQL run_sql( sql=""" SELECT DATE_TRUNC('day', block_time) as day, COUNT(*) as tx_count FROM ethereum.transactions WHERE block_time > NOW() - INTERVAL '7' DAY GROUP BY 1 ORDER BY 1 LIMIT 100 """, performance="medium" ) ``` ### Read Cached Results (Zero Credits) Access the resource `dune://query/123456/latest` to get cached results without consuming execution credits. ## DuneSQL Tips - Addresses are bytearrays: use `0x...` literals directly - Date intervals: `NOW() - INTERVAL '7' DAY` - Prefer decoded tables: `uniswap_v3_ethereum.Factory_evt_PoolCreated` - Always include `LIMIT` to prevent timeouts ## Development ```bash # Clone the repository git clone https://github.com/your-org/mcp-server-dune cd mcp-server-dune # Create virtual environment python -m venv venv venv\Scripts\activate # Windows # source venv/bin/activate # Linux/macOS # Install in development mode pip install -e ".[dev]" # Run tests pytest # Run the server locally python -m mcp_server_dune ``` ## License MIT