Dune

Dune MCP is a defensive, token-aware gateway that lets LLMs securely interact with Dune Analytics. It emphasizes reusing existing queries and safeguarding your credits, providing a safer, more efficient way to access data without flooding your API with raw SQL.

How to use

You connect your MCP client to the Dune MCP server to perform searches, inspect queries, run queries, and export results. You can start by using the standard local server setup and then configure your client to point to the MCP server. Use the built-in tools to search public queries, browse your own work, view query details, and execute queries with budget checks. The system prioritizes reusing existing queries before generating new SQL and returns previews to minimize token usage.

How to install

Prerequisites: ensure you have a modern Python environment and the UV tool installed for local MCP execution.

# Option A: Install via UV tool (recommended)
uv tool install dune-mcp

# Or via pip
pip install dune-mcp

# To update later
uv tool upgrade dune-mcp
# Or
pip install --upgrade dune-mcp

Option 1: Run with a prebuilt MCP (Dune MCP as a local server)

Configure Claude Desktop to connect to the local MCP server by adding the following configuration. This runs a local MCP process and exposes the server as dune.

{
  "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

If you prefer running from source, follow these steps to clone, set up, and run the MCP server locally.

# 1. Clone the repository
git clone https://github.com/nice-bills/dune-mcp.git
cd dune-mcp

# 2. Start the server using UV (as shown in the source flow)
uv sync
cp .env.example .env
# Edit .env with your keys

Claude Desktop configuration for local source run

Configure Claude Desktop to launch the MCP server from the local source path.

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

Available tools

search_public_queries

Search existing public queries by keyword (free and fast) for ideas and reusable SQL.

list_user_queries

List queries by a user handle to review your own or others’ work.

search_spellbook

Search the official Dune Spellbook repository for tables and schemas related to a topic.

get_spellbook_file_content

View the SQL or schema content of a Spellbook file to understand structure.

get_query_details

Inspect the SQL and parameters of a specific query by ID.

get_table_schema

Retrieve the column definitions for a given table to understand its schema.

execute_query

Run a selected query asynchronously with budget checks to prevent overspending.

get_job_status

Poll for the completion status of an executed query job.

get_job_results_summary

Obtain a lightweight preview (top 5 rows) and summary statistics for results.

export_results_to_csv

Download the full dataset of a completed job as CSV.

analyze_results

Analyze results to detect outliers and trends.

analyze_query_error

Get AI-driven suggestions to fix failed queries based on error messages.

create_query

Save a new query to your Dune account with a descriptive name.

update_query

Modify an existing query by ID with new SQL.

archive_query

Delete or archive a query by ID.