spice-mcp
An MCP server that provides AI agents with direct access to Dune Analytics data. Execute queries, discover schemas and tables, and manage saved queries—all through a clean, type-safe interface optimized for AI workflows.
Discover High-Quality Tables: Leverages Dune Spellbook, Dune's official GitHub repository of curated dbt models, to surface verified, production-ready tables with rich metadata.
Why spice-mcp?
- Agent-friendly: Designed for AI agents using the Model Context Protocol (MCP)
- High-Quality Discovery: Leverages Dune Spellbook's GitHub repository to find verified, production-ready tables with rich metadata
- Efficient: Polars-first pipeline keeps data lazy until needed, reducing memory usage
- Discovery: Built-in tools to explore Dune's extensive blockchain datasets from both Dune API and Spellbook
- Type-safe: Fully typed parameters and responses with FastMCP
- Reproducible: Automatic query history logging and SQL artifact storage
Quick Start
-
Install:
uv pip install spice-mcp -
Set API key (choose one method):
- Option A: Create a
.envfile in your project root:echo "DUNE_API_KEY=your-api-key-here" > .env - Option B: Export in your shell:
export DUNE_API_KEY=your-api-key-here
- Option A: Create a
-
Use with Cursor IDE: Add to Cursor Settings → MCP Servers:
{ "name": "spice-mcp", "command": "spice-mcp", "env": { "DUNE_API_KEY": "your-dune-api-key-here" } }
Note: Query history logging is enabled by default. Logs are saved to logs/queries.jsonl (or ~/.spice_mcp/logs/queries.jsonl if not in a project directory). To customize paths, set SPICE_QUERY_HISTORY and SPICE_ARTIFACT_ROOT environment variables.
Admin operations (create/update/fork/archive/unarchive) are logged with action_type="admin_action" and include query_id for traceability.
Core Tools
| Tool | Description | Key Parameters |
|---|---|---|
dune_query | Execute queries by ID, URL, or raw SQL | query (str), parameters (object), limit (int), offset (int), format (preview|raw|metadata|poll), refresh (bool), timeout_seconds (float) |
dune_query_info | Get metadata for a saved query | query (str - ID or URL) |
dune_discover | Unified discovery across Dune API and Spellbook (returns verified tables only). Leverages Dune Spellbook GitHub repository for high-quality, curated tables. | keyword (str|list), schema (str), limit (int), source (dune|spellbook|both), include_columns (bool) |
dune_describe_table | Get column metadata for a table | schema (str), table (str) |
dune_health_check | Verify API key and configuration | (no parameters) |
dune_query_create | Create a new saved query | name (str), query_sql (str), description (str), tags (list), parameters (list) |
dune_query_update | Update an existing saved query | query_id (int), name (str), query_sql (str), description (str), tags (list), parameters (list) |
dune_query_fork | Fork an existing saved query | source_query_id (int), name (str) |
dune_query_archive | Archive a saved query | query_id (int) |
dune_query_unarchive | Unarchive a saved query | query_id (int) |
Resources
spice:history/tail/{n}— View last N lines of query history (1-1000)spice:artifact/{sha}— Retrieve stored SQL by SHA-256 hash
What is Dune?
Dune is a crypto data platform providing curated blockchain datasets and a public API. It aggregates on-chain data from Ethereum, Solana, Polygon, and other chains into queryable SQL tables. See the Dune Docs for more information.
What is Dune Spellbook?
Dune Spellbook is Dune's official GitHub repository containing thousands of curated dbt models. These models represent high-quality, production-ready tables that are:
- Verified: All tables are verified to exist in Dune before being returned
- Well-documented: Rich metadata including column descriptions and types
- Maintained: Regularly updated by the Dune community and team
- Production-ready: Used by analysts and dashboards across the ecosystem
spice-mcp automatically clones and parses the Spellbook repository to discover these high-quality tables, parsing dbt config blocks to resolve actual Dune table names and verifying their existence before returning them to you.
Installation
From PyPI (recommended):
uv pip install spice-mcp
From source:
git clone https://github.com/Evan-Kim2028/spice-mcp.git
cd spice-mcp
uv sync
uv pip install -e .
Requirements: Python 3.13+
Documentation
- Tool Reference — Complete tool documentation with parameters
- Architecture — Code structure and design patterns
- Discovery Guide — How to explore Dune schemas and tables
- Dune API Guide — Understanding Dune's data structure
- Configuration — Environment variables and settings
License
See LICENSE file for details.