dune query mcp

Local 2025-09-01 01:00:07 0
Research and Data @olaxbt/dune-query-mcp

A bridge that connects Dune Analytics blockchain data to AI applications through Model Control Protocol, allowing LLMs to access on-chain data via natural language interactions.

Version Python

A modern bridge connecting Dune Analytics data to intelligent agents through Model Control Protocol (MCP).

Overview

dune-query-mcp enables seamless integration of blockchain data analytics into your AI applications. By leveraging Dune Analytics powerful query capabilities with the Model Control Protocol, this service allows LLMs and other AI systems to access on-chain data through simple, natural language interactions.

Core Capabilities

Data Retrieval Tools

Tool Description Use Case
get_latest_result Retrieves pre-computed query results Quick access to existing data
run_query Executes a query on-demand Real-time data analysis

Data Format

All data is returned in CSV format, providing: - Universal compatibility - Easy parsing by most data analysis tools - Human-readable output

Getting Started

System Requirements

Quick Setup

  1. Clone & Navigate 

    git clone https://github.com/olaxbt/dune-query-mcp-mcp.git
cd dune-query-mcp

  2. Environment Setup 

    # Create virtual environment
python -m venv .venv

# Activate it
source .venv/bin/activate  # Linux/Mac
# or
.venvScriptsactivate     # Windows

# Install dependencies
pip install -r requirements.txt

  3. Configure API Access 

    # Copy example config
cp .env.example .env

# Edit with your API key
echo "DUNE_API_KEY=your_key_here" > .env

Usage

Running the Service

dune-query-mcp offers two ways to run:

As MCP Service

python run.py
This starts the MCP service on default port 8000.

As Web Server

python flask_app.py
This provides access to the web interface and REST API endpoints.

Integrating with Applications

MCP Client Integration

from mcp.client import Client

# Connect to Dune-query-mcp
client = Client("http://localhost:8000")

# Get latest results for a query
csv_data = client.call("get_latest_result", query_id=1234567)

# Execute a query
query_results = client.call("run_query", query_id=1234567)

REST API

Endpoint Method Description
/dune/health GET Service health check
/dune/query/{query_id}/latest GET Retrieve latest results
/dune/query/{query_id}/execute POST Run a query

Example REST Call: 

curl -X GET http://localhost:5000/dune/query/1234567/latest

Architecture

dune-query-mcp/
├── app/                       # Application core
│   ├── __init__.py            # Flask & MCP setup
│   ├── routes/                # API endpoint definitions
│   │   └── dune_routes/       # Dune Analytics routes
│   │   └── templates/             # Web interface
│   └── templates/             # Web interface
├── config/                    # Configuration files
├── logs/                      # Runtime logs
├── flask_app.py               # Web server entry point
├── run.py                     # MCP server entry point
└── requirements.txt           # Dependencies

Advanced Configuration

Environment Variables

Variable Purpose Default
DUNE_API_KEY Authentication for Dune API None (Required)
PORT Server port 8000

Performance Tuning

For high-volume query execution:

# Set a higher timeout for long-running queries
export DUNE_QUERY_TIMEOUT=600  # 10 minutes in seconds

Troubleshooting

Common issues and solutions:

Problem Solution
API Key errors Ensure .env file exists with valid key
Timeout errors Increase timeout for complex queries
CSV parsing issues Check query returns proper tabular data

Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Commit your changes: git commit -am Add some amazing feature
  4. Push to the branch: git push origin feature/amazing-feature
  5. Open a Pull Request

License

This project is released under the MIT License. See LICENSE file for details.

Acknowledgments