mcp-server-dune

A Model Context Protocol (MCP) server for integrating AI agents with Dune Analytics blockchain data.

Requirements

• Python 3.11+
• Dune Analytics API key

Features

Tools

• run_query - Execute saved Dune queries and wait for results
• submit_query - Submit queries asynchronously for long-running jobs
• get_execution_status - Check the status of running queries
• get_execution_results - Retrieve results from completed executions
• run_sql - Execute raw ad-hoc DuneSQL queries
• create_query - Save new queries to your Dune library
• update_query - Modify existing queries
• archive_query - Archive queries from active workspace

Resources (dune:// scheme)

• dune://query/{id}/latest - Cached results (zero credits)
• dune://query/{id}/sql - Query SQL definition
• dune://execution/{id}/status - Execution job status

Prompts

• generate_dune_sql - Guide for writing valid DuneSQL
• analyze_result - Guide for interpreting query results

Installation

# Install from source
pip install -e .

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

Configuration

Set your Dune API key as an environment variable:

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

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "dune": {
      "command": "python",
      "args": ["-m", "mcp_server_dune"],
      "env": {
        "DUNE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Direct Execution

# Run the server
python -m mcp_server_dune

Usage Examples

Execute a Saved Query

# Run query ID 123456 with parameters
run_query(
    query_id=123456,
    params={"token_address": "0x..."},
    performance="medium",
    limit=50
)

Execute Ad-Hoc SQL

# Run raw DuneSQL
run_sql(
    sql="""
    SELECT DATE_TRUNC('day', block_time) as day,
           COUNT(*) as tx_count
    FROM ethereum.transactions
    WHERE block_time > NOW() - INTERVAL '7' DAY
    GROUP BY 1
    ORDER BY 1
    LIMIT 100
    """,
    performance="medium"
)

Read Cached Results (Zero Credits)

Access the resource dune://query/123456/latest to get cached results without consuming execution credits.

DuneSQL Tips

• Addresses are bytearrays: use 0x... literals directly
• Date intervals: NOW() - INTERVAL '7' DAY
• Prefer decoded tables: uniswap_v3_ethereum.Factory_evt_PoolCreated
• Always include LIMIT to prevent timeouts

Development

# Clone the repository
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

License

MIT