Dune Analytics MCP Server for AI Agents

Overview

This MCP (Model Context Protocol) server bridges AI agents and Dune Analytics by streaming query results and exposing them as live, agent-consumable resources. Instead of polling Dune APIs for completed reports, the server invokes Dune queries, monitors progress, and pushes partial and final results to connected agents. That makes it simpler to feed up-to-date analytics into decision-making workflows, conversational agents, and automation pipelines.

The server is particularly useful when agents need iterative access to large or long-running queries: agents can start a query, receive incremental rows as they arrive, and take actions (summaries, alerts, trades) without waiting for the full query to finish. The implementation focuses on a lightweight API and streaming interfaces so developers can integrate analytics-driven context into LLMs or other AI systems with minimal glue code.

Features

• Stream Dune Analytics query results incrementally (Server-Sent Events / HTTP streaming)
• Start and monitor query execution from an HTTP API
• Expose progress, partial rows, and final result sets to connected agents
• Simple configuration via environment variables or Docker
• Basic authentication and rate limiting hooks (pluggable)
• Example client snippets for JavaScript and Python to receive streamed data
• Logging and optional caching of recent query outputs

Installation / Configuration

Clone the repository and install dependencies. This project can run locally or inside Docker.

Bash (clone + install):

git clone https://github.com/kukapay/dune-analytics-mcp.git
cd dune-analytics-mcp
# If Node.js/TypeScript project:
npm install
# Or for Python-based server:
pip install -r requirements.txt

Environment variables (example):

export DUNE_API_KEY="your_dune_api_key"
export MCP_PORT=8080
export MCP_BIND_ADDRESS="0.0.0.0"
# Optional:
export CACHE_TTL_SECONDS=300
export AUTH_TOKEN="your_optional_server_token"

Run the server (examples):

# Node / npm
npm run build
npm start

# Or direct node
node dist/server.js

# Docker
docker build -t dune-mcp .
docker run -p 8080:8080 \
  -e DUNE_API_KEY="$DUNE_API_KEY" \
  -e MCP_PORT=8080 \
  dune-mcp

Configuration tips:

• Set a short cache TTL when using agents that need frequent fresh data.
• Protect the server with an AUTH_TOKEN or upstream proxy if exposed publicly.
• Monitor rate limits on your Dune account; the server can queue requests but not bypass Dune quotas.

Available Resources

The server exposes a small set of HTTP endpoints and a streaming interface suited for AI agents. Example endpoints:

Typical streaming payloads use SSE with event types like row, progress, and complete. Example SSE event bodies are JSON objects containing a small batch of rows or status metadata.

Client examples:

JavaScript (EventSource):

const url = "http://localhost:8080/query/stream/12345?auth=TOKEN";
const es = new EventSource(url);
es.addEventListener('row', e => {
  const payload = JSON.parse(e.data);
  console.log("Row batch:", payload.rows);
});
es.addEventListener('complete', e => {
  console.log("Query complete:", JSON.parse(e.data));
  es.close();
});

Python (requests, streaming):

import requests
with requests.get("http://localhost:8080/query/stream/12345", stream=True) as r:
    for line in r.iter_lines():
        if not line:
            continue
        # Decode SSE-like lines
        print(line.decode())

Use Cases

1. Real-time agent-driven dashboards

   • An agent monitors blockchain activity on Dune and updates a dashboard as new rows arrive. The MCP server streams partial results, enabling the dashboard to reflect near-real-time analytics without frequent full query re-runs.

2. Automated trading or alerting systems

   • Trading agents subscribe to a streaming query that calculates on-chain signals. When specific thresholds are observed in partial results, the agent executes trades or sends alerts immediately rather than after batch completion.

3. Conversational analytics assistants

   • A chat-based AI answers user questions using fresh on-chain data. The assistant triggers a Dune query via the MCP server and can provide progressive summaries while the query runs, then refine answers using the final data.

4. Scheduled reports with incremental verification

   • Reporting bots launch large aggregation queries and validate intermediate checkpoints as rows arrive. This reduces the time between data availability and automated report generation.

Notes for Developers

• Handle backpressure: downstream agents should be prepared to process frequent row events or unsubscribe when overloaded.
• Respect Dune quotas: batching and caching help reduce load on the upstream Dune API.
• Security: do not embed raw API keys in client code. Use server-side auth and short-lived tokens for agent access.
• Extendability: the server is built to allow adding custom hooks (post-processing, enrichment, storage) on streamed events.

For repository-specific usage details, check the project’s example clients and configuration files in the repo.