Dune

You run an MCP server that connects AI agents to Dune Analytics data. It lets you save, run, and manage Dune queries, fetch results, and read cached data without consuming credits. This guide walks you through practical setup, installation, and usage so you can start querying Dune from your agents right away.

How to use

Start the Dune MCP server locally and connect your MCP client to it. You can execute saved Dune queries, submit long-running queries asynchronously, check execution status, retrieve results, and run ad-hoc DuneSQL. You will also create and manage queries in your Dune library, archive obsolete ones, and use the provided prompts to guide DuneSQL writing and result interpretation.

How to install

Prerequisites you need before installation are Python 3.11 or newer and a Dune Analytics API key.

Install from source or install dependencies directly.

pip install -e .

# Or install dependencies directly
pip install fastmcp>=2.0.0 dune-client>=1.10.0 pydantic>=2.0.0

Configuration and running the server

Set your Dune API key so the MCP server can authenticate with Dune Analytics.

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

Direct execution to start the server

Run the MCP server directly in your environment once the dependencies are installed and the API key is set.

python -m mcp_server_dune

Usage patterns after startup

Use your MCP client to execute saved queries with run_query by providing a query ID and any needed parameters. You can also submit ad-hoc DuneSQL with run_sql, check execution status with get_execution_status, and fetch completed results with get_execution_results. Cached results are available through dune://query/{id}/latest without consuming credits.

Examples of core actions you can perform

• Run a saved query by ID and supply parameters like addresses or tokens.

• Submit a long-running query asynchronously to keep your client responsive.

• Execute a raw DuneSQL statement to probe data on demand.

Notes on tools and resources

The server exposes a set of tools to interact with Dune data: run_query, submit_query, get_execution_status, get_execution_results, run_sql, create_query, update_query, and archive_query. It also provides prompts like generate_dune_sql to help construct valid DuneSQL and analyze_result to interpret results.

Security and keys

Keep your DUNE_API_KEY secure. Do not hard-code it in your codebase. Use environment variables or secret management in your deployment environment.

Troubleshooting tips

If you encounter authentication errors, double-check that DUNE_API_KEY is correctly exported in your shell or your deployment environment. Ensure Python 3.11+ is in use and that all dependencies are installed as shown above.

Notes

This MCP server is designed to run locally or in your preferred environment where Python is available. The key workflow is to start the server and connect your MCP client to the running process to perform Dune analytics tasks through the MCP interface.

Configuration snippets

# Claude Desktop configuration example for the Dune MCP server
{
  "mcpServers": {
    "dune": {
      "command": "python",
      "args": ["-m", "mcp_server_dune"],
      "env": {
        "DUNE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Development and testing

To run the development setup locally, set up a virtual environment, install dependencies in editable mode, and run tests or start the server as shown in the steps.

# Clone and install in development mode
# 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

Available tools

run_query

Execute a saved Dune query by ID, with optional parameters, and receive results.

submit_query

Submit a Dune query asynchronously for long-running executions.

get_execution_status

Check the status of an ongoing execution job.

get_execution_results

Retrieve results from a completed execution.

run_sql

Execute a raw DuneSQL statement against the Dune data source.

create_query

Save a new Dune query to your library for reuse.

update_query

Modify properties or parameters of an existing Dune query.

archive_query

Archive a query from your active workspace.

generate_dune_sql

Guide for constructing valid DuneSQL queries.

analyze_result

Guide for interpreting query results and extracting insights.