Skip to main content
Glama

Dune MCP (Model Context Protocol)

PyPI version Downloads

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

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

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

  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.

# 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_KEY

Configuration

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 # Optional

Usage

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.main

Best Practices

Zero-Credit Schema Discovery

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

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

  2. 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.

  3. Alternatively, use search_public_queries("topic") to find existing queries on the topic.

  4. Use get_query_details(id) 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

Available Tools

17 tools
analyze_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

    B3.2/5.0

    Scored across 17 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      A
      quality
      D
      maintenance
      Dune 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 curate
      19
      MIT