Dune MCP (Model Context Protocol)

A defensive, token-aware MCP server for Dune Analytics.

This project enables LLMs (like Claude, or custom agents) to securely interact with Dune Analytics. It acts as a "Smart Gateway" that prioritizes Query Reuse and Budget Safety over raw SQL generation, protecting your API credits and reducing token consumption.

Quick Start

Option 1: Install via PyPI (Recommended)

1. Install:

   # The easiest way to manage tools uv tool install dune-mcp # OR using pip pip install dune-mcp

   To Update:

   uv tool upgrade dune-mcp # OR pip install --upgrade dune-mcp

2. Configure Claude Desktop: Add this to your claude_desktop_config.json:

   { "mcpServers": { "dune": { "command": "dune-mcp", "env": { "DUNE_API_KEY": "your_api_key", "DUNE_USER_HANDLE": "your_username", "GITHUB_TOKEN": "optional_github_token" } } } }

Option 2: Run from Source

1. Clone & Setup:

   git clone https://github.com/nice-bills/dune-mcp.git cd dune-mcp uv sync cp .env.example .env # Edit .env with your keys

2. Configure Claude Desktop:

   { "mcpServers": { "dune": { "command": "uv", "args": ["run", "src/main.py"], "cwd": "/absolute/path/to/dune-mcp" } } }

Usage

Once connected, you can ask Claude things like:

• "Find queries about Uniswap volume on Base."

• "List my recent queries."

• "Execute query ID 12345."

• "Analyze the results of the last query."

Zero-Credit Schema Discovery

• Google-like Search: Reverse-engineered GraphQL integration allows searching public queries by keyword (e.g., "uniswap volume").

• Portfolio Browsing: List queries by user handle to access your own or others' work.

• Budget Manager: Deterministic guards that prevent credit exhaustion.

• Token-Optimized: Returns "Indices" (summaries) instead of raw schemas. Results are previewed (top 5 rows), not streamed in full.

• Query Reuse First: Tools encourage searching existing community queries before generating new SQL.

• CSV Export: "Escape hatch" to download full datasets to disk instead of flooding the LLM context.

Toolset

1. search_public_queries(query): Search existing queries by keyword (free & fast).

2. list_user_queries(handle, limit): List queries by user (e.g., "bils").

3. search_spellbook(keyword): Search the official Dune Spellbook GitHub repo for tables (e.g., "uniswap").

4. get_spellbook_file_content(path): View the SQL or schema of a Spellbook file.

5. get_query_details(query_id): Inspect SQL and parameters (on demand).

6. get_table_schema(table_name): Get columns for a specific table (Costs Credits).

7. execute_query(query_id): Run a query (async, budget-checked).

8. get_job_status(job_id): Poll for completion.

9. get_job_results_summary(job_id): Get a lightweight preview (5 rows + stats).

10. export_results_to_csv(job_id): Download the full dataset.

11. analyze_results(job_id): Detect outliers and trends in data.

12. analyze_query_error(error_message, query_sql): Get AI-driven fix suggestions for failed queries.

13. create_query(name, sql): Save a new query to your Dune account.

14. update_query(query_id, sql): Modify an existing query.

15. archive_query(query_id): Delete/Archive a query.

Installation

This project uses uv for fast package management.

Configuration

Add your handle to .env to allow the MCP to auto-detect your queries:

Usage

Option 1: Claude Desktop

Add this to your claude_desktop_config.json:

Option 2: MCP Inspector (Web UI)

Test the tools interactively in your browser.

Best Practices

Zero-Credit Schema Discovery

To find table names or column structures without consuming Dune credits:

1. Use to find official Dune Spellbook models (SQL files) and schema definitions (schema.yml) that match your topic.

2. Use to view the SQL or schema definition. This directly gives you the table name and its structure.

3. Alternatively, use to find existing queries on the topic.

4. Use to inspect their SQL.

5. Extract the table names (e.g., uniswap_v3_ethereum.Factory_evt_PoolCreated) from the SQL.

This "Rosetta Stone" approach is faster, safer, and cheaper than blindly querying the schema.

Safety Principles

1. Never stream raw data: 100k rows = Token Death. We stream previews + stats.

2. Two-Phase Reasoning: Plan (Search/Estimate) → Execute.

3. MCP Does the Boring Work: We calculate min/max/avg in Python, not the LLM.

Limitations

• Paid Features: The create_query, update_query, and archive_query tools require a Paid Dune Plan (Plus or Premium) to access the write-access API endpoints. Free tier users will receive a 403 Forbidden error.

• Rate Limits: Be mindful of Dune's API rate limits, especially on the free tier.

• WAF: The search tools use an unofficial method and may be temporarily blocked by Cloudflare. The MCP handles this by suggesting alternatives.

License

MIT