dune-mcp
The Dune MCP server enables secure, token-efficient interaction with Dune Analytics through LLMs, prioritizing query reuse over raw SQL generation with built-in budget protection.
Query Discovery & Inspection:
Search public queries by keyword to discover existing solutions and table names
List queries by user handle to browse specific accounts
Get detailed SQL and parameters for any query by ID
Search the official Dune Spellbook GitHub repository for zero-credit table discovery
View Spellbook file content to inspect SQL models and schema definitions
Query Execution & Results:
Execute queries by ID with optional parameters and get a tracking job ID
Poll job status with automatic 30-second intervals
Get lightweight result previews (first 5 rows + statistics) to avoid token overflow
Export full results to CSV as an escape hatch for large datasets
Query Management (Requires Paid Plan):
Create new queries and save to your Dune account
Update existing queries with new SQL or descriptions
Archive or delete queries
Analysis & Error Handling:
Analyze results to detect outliers (Z-score > 3) and trends automatically
Get AI-driven fix suggestions for failed queries based on error messages and SQL
Budget & Account Monitoring:
Check account status for remaining credits and budget limits
Monitor session budget to track usage in the current session
Built-in guards prevent credit exhaustion
Schema Exploration:
Get table schema for specific tables (note: consumes Dune credits via zero-row query)
Use Spellbook search for zero-credit schema discovery as preferred alternative
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@dune-mcp search for recent queries about Uniswap trading volume"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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)
Install:
# The easiest way to manage tools uv tool install dune-mcp # OR using pip pip install dune-mcpTo Update:
uv tool upgrade dune-mcp # OR pip install --upgrade dune-mcpConfigure 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
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 keysConfigure Claude Desktop:
{ "mcpServers": { "dune": { "command": "uv", "args": ["run", "src/main.py"], "cwd": "/absolute/path/to/dune-mcp" } } }
Related MCP server: Spice 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
search_public_queries(query): Search existing queries by keyword (free & fast).list_user_queries(handle, limit): List queries by user (e.g., "bils").search_spellbook(keyword): Search the official Dune Spellbook GitHub repo for tables (e.g., "uniswap").get_spellbook_file_content(path): View the SQL or schema of a Spellbook file.get_query_details(query_id): Inspect SQL and parameters (on demand).get_table_schema(table_name): Get columns for a specific table (Costs Credits).execute_query(query_id): Run a query (async, budget-checked).get_job_status(job_id): Poll for completion.get_job_results_summary(job_id): Get a lightweight preview (5 rows + stats).export_results_to_csv(job_id): Download the full dataset.analyze_results(job_id): Detect outliers and trends in data.analyze_query_error(error_message, query_sql): Get AI-driven fix suggestions for failed queries.create_query(name, sql): Save a new query to your Dune account.update_query(query_id, sql): Modify an existing query.archive_query(query_id): Delete/Archive a query.
Installation
This project uses uv for fast package management.
# 1. Clone the repo
git clone https://github.com/nice-bills/dune-mcp.git
cd dune-mcp
# 2. Setup config
cp .env.example .env
# Edit .env and add your DUNE_API_KEYConfiguration
Add your handle to .env to allow the MCP to auto-detect your queries. You can also provide multiple API keys for load rotation:
DUNE_API_KEY=your_key
# OR
DUNE_API_KEYS=key1,key2,key3 # Comma-separated list for rotation
DUNE_USER_HANDLE=your_username # OptionalUsage
Option 1: Claude Desktop
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"dune": {
"command": "uv",
"args": ["run", "-m", "src.main", "--directory", "/path/to/dune-mcp"]
}
}
}Option 2: MCP Inspector (Web UI)
Test the tools interactively in your browser.
npx @modelcontextprotocol/inspector uv run -m src.mainBest Practices
Zero-Credit Schema Discovery
To find table names or column structures without consuming Dune credits:
Use
search_spellbook("keyword")to find official Dune Spellbook models (SQL files) and schema definitions (schema.yml) that match your topic.Use
get_spellbook_file_content("path/to/file.sql")to view the SQL or schema definition. This directly gives you the table name and its structure.Alternatively, use
search_public_queries("topic")to find existing queries on the topic.Use
get_query_details(id)to inspect their SQL.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
Never stream raw data: 100k rows = Token Death. We stream previews + stats.
Two-Phase Reasoning: Plan (Search/Estimate) → Execute.
MCP Does the Boring Work: We calculate min/max/avg in Python, not the LLM.
Limitations
Paid Features: The
create_query,update_query, andarchive_querytools 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
Available Tools
17 toolsanalyze_query_errorC
Analyze failed queries and suggest fixes (e.g. for 'Column not found').
Inputs: error_message (required), query_sql (required). Returns: result
analyze_resultsC
Detect outliers (Z-score > 3) and trends in query results.
Inputs: job_id (required). Returns: result
archive_queryC
Archive/Delete a query. (Requires Paid Plan)
Inputs: query_id (required). Returns: result
create_queryA
Save a new query to Dune. Returns Query ID. (Requires Paid Plan)
Inputs: name (required), sql (required), description. Returns: result
execute_queryC
Execute a query by ID. Returns Job ID.
Inputs: query_id (required), params. Returns: result
export_results_to_csvC
Download full query results to local CSV.
Inputs: job_id (required). Returns: result
get_account_statusA
Check remaining credits and budget limits.
Inputs: no named parameters. Returns: result
get_job_results_summaryB
Get result preview (5 rows) and stats.
Inputs: job_id (required). Returns: result
get_job_statusC
Check query execution status. Polls for 30s.
Inputs: job_id (required). Returns: result
get_query_detailsB
Get SQL and parameters for a query ID.
Inputs: query_id (required). Returns: result
get_session_budgetB
Check remaining queries/credits for this session.
Inputs: no named parameters. Returns: result
get_spellbook_file_contentC
Fetch raw content of a Spellbook file from GitHub.
Inputs: path (required). Returns: result
get_table_schemaA
Get columns for a table. Costs Credits (runs SELECT * LIMIT 0).
Inputs: table_name (required). Returns: result
list_user_queriesC
List queries by user handle.
Inputs: handle, limit. Returns: result
search_public_queriesB
Search public queries by keyword. Use this to discover table names from existing SQL.
Inputs: query (required). Returns: result
search_spellbookA
Search GitHub Spellbook for official tables (.sql/.yml). Zero-credit schema discovery.
Inputs: keyword (required). Returns: result
update_queryC
Update SQL/description of an existing query. (Requires Paid Plan)
Inputs: query_id (required), sql (required), description. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools target distinct resources and actions, and the naming/descriptions make the query lifecycle clear. The main ambiguity is between the two credit/budget tools and to a lesser degree between search_public_queries and search_spellbook, but descriptions mostly help resolve it.
All tool names follow a consistent verb_noun snake_case pattern (get_, create_, update_, search_, execute_, export_). The verbs and objects are predictable across query, job, and schema domains, making the tool set very easy to navigate.
17 tools is on the higher side for an MCP server, but it is justified by covering query management, execution, results, schema discovery, billing, and analysis. It feels slightly heavy, but each tool addresses a distinct part of the Dune workflow and no obvious filler tools exist.
The server covers the full query lifecycle: create/update/archive, execute, poll status, and obtain results, plus schema discovery and budget management. Minor gaps exist, such as no explicit job cancellation and no tool to fetch full results as structured data in-context, but the core workflows are workable.
Maintenance
Related MCP Connectors
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
Query BigQuery, Snowflake, Redshift & Azure Synapse with natural language
Query PostgreSQL databases in plain English — LLM-generated, safety-validated SQL.
The grounded data layer for any LLM: governed SQL, metrics, lineage and catalog over your data.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAllows LLM agents and MCP clients to analyze blockchain data including wallet balances, token information, and transaction history across EVM and Solana chains through the Dune API.20 npm4MIT
- AlicenseBqualityDmaintenanceEnables querying and analyzing blockchain data from Dune Analytics with Polars-optimized workflows, including schema discovery, Sui package exploration, and query management through natural language.101MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to query and analyze blockchain data from Dune Analytics, supporting execution of saved queries, ad-hoc DuneSQL queries, and access to cached results with parameter support.MIT
- AlicenseAqualityDmaintenanceDune MCP Server connects your AI assistant to Dune Analytics, the leading platform for blockchain data. Execute SQL queries across Ethereum, Solana, and 20+ chains to analyze DEX trades, token transfers, NFT sales, and wallet activity. Manage saved queries, upload custom datasets, and access curate19MIT