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 definitiondune://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
LIMITto 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