Dune MCP

MCP (Model Context Protocol) is an open standard for connecting AI applications to external systems. Dune MCP is Dune’s official remote MCP server. It gives your agent direct, structured access to Dune workflows: discover relevant datasets, create and run SQL queries, inspect execution results, manage visualizations, and build dashboards — all in the same conversation. This is the fastest way to move from prompt to reliable onchain analysis. See also Agents on dune.com.

Setup and Usage

Authentication

To connect, sign in with your Dune account. You do not need an API key. Most agents only need:

Name: Dune
url: https://api.dune.com/mcp/v1

When you add the server, your agent opens the Dune sign-in page in your browser. After you sign in, you go back to your agent and it is ready to use. This sign-in uses OAuth 2.0. The technical details are in Connection Details. If your agent runs where it cannot open a browser, see Headless and CI environments.

Setup examples

Claude Code

claude mcp add --scope user --transport http dune https://api.dune.com/mcp/v1

Then run /mcp in Claude Code and select dune to sign in.

Claude Desktop

OpenCode

Once added run opencode mcp auth Dune and it will open up a browser where you can log into Dune.

Codex

codex mcp add dune --url "https://api.dune.com/mcp/v1"

# Login after adding the MCP
codex mcp login dune

Known issue: “Transport closed” errors during long-running queriesCodex’s MCP client has a default tool timeout of 60 seconds. When getExecutionResults polls for a query that takes longer than this, Codex terminates the connection. Due to a known Codex bug, the MCP transport does not auto-reconnect after a timeout - all subsequent tool calls will fail with Transport closed until you start a new session.Workaround: Increase the Codex tool timeout in your config:

[mcp_servers.dune]
url = "https://api.dune.com/mcp/v1"
tool_timeout_sec = 300

Cursor

tl:dr; Add this configuration to your Cursor settings, then sign in with your Dune account when Cursor asks:

{
  "mcpServers": {
    "dune": {
      "url": "https://api.dune.com/mcp/v1"
    }
  }
}

Headless and CI environments

Use this only when your agent runs where it cannot sign in with a browser, for example in CI. In all other cases, sign in with your Dune account as shown above. Send your Dune API key in the x-dune-api-key header. Do not put the key in the URL.

claude mcp add --scope user --transport http dune https://api.dune.com/mcp/v1 --header "x-dune-api-key: <dune-api-key>"

For clients that use a JSON config:

{
  "mcpServers": {
    "dune": {
      "url": "https://api.dune.com/mcp/v1",
      "headers": {
        "x-dune-api-key": "<dune-api-key>"
      }
    }
  }
}

Tools and Resources Inventory

Tools

Category	Tool	Description
Discovery	`searchDocs`	Search Dune docs for guides, examples, and API references
Discovery	`searchTables`	Find tables by protocol, chain, category, or schema
Discovery	`listBlockchains`	List indexed blockchains with table counts
Discovery	`searchTablesByContractAddress`	Find decoded event/call tables for a contract address
Discovery	`getTableSize`	Estimate the data scanned by a query for one or more tables
Query Lifecycle	`createDuneQuery`	Create and save a new Dune query
Query Lifecycle	`getDuneQuery`	Fetch SQL and metadata for an existing query
Query Lifecycle	`updateDuneQuery`	Update SQL, title, description, tags, or parameters
Query Lifecycle	`executeQueryById`	Execute a saved query and return an execution ID
Query Lifecycle	`getExecutionResults`	Fetch status and results for a query execution
Materialized Views	`createMaterializedView`	Materialize a saved query’s results into a queryable table, with an optional scheduled refresh
Materialized Views	`listMaterializedViews`	List materialized views owned by you or your team
Materialized Views	`getMaterializedView`	Fetch a materialized view’s metadata, size, and execution status
Materialized Views	`refreshMaterializedView`	Re-run the source query on demand to update the materialized table
Materialized Views	`updateMaterializedView`	Change the performance tier or add/change/remove the refresh schedule
Materialized Views	`deleteMaterializedView`	Permanently delete a materialized view
Visualization	`generateVisualization`	Create charts, counters, and tables from query results
Visualization	`getVisualization`	Fetch details of an existing visualization
Visualization	`updateVisualization`	Update an existing visualization’s configuration
Visualization	`deleteVisualization`	Delete a visualization
Visualization	`listQueryVisualizations`	List all visualizations attached to a query
Dashboard	`createDashboard`	Create a new dashboard with widgets and layout
Dashboard	`getDashboard`	Fetch details of an existing dashboard
Dashboard	`updateDashboard`	Update a dashboard’s content, layout, or metadata
Dashboard	`archiveDashboard`	Archive a dashboard
Folders	`listDuneFolders`	List folders in your library, with item counts
Folders	`getDuneFolder`	Fetch a folder with its subfolders, queries, and dashboards
Folders	`createDuneFolder`	Create a folder at the top level or inside another folder
Folders	`updateDuneFolder`	Rename a folder or change its description, color, or icon
Folders	`moveDuneFolder`	Move a folder under another folder or to the top level
Folders	`deleteDuneFolder`	Delete a folder, or a folder and everything inside it
Folders	`moveContentToFolder`	Move queries and dashboards into a folder or out of folders
Schedules	`listSchedules`	List query, dashboard, and materialized view schedules
Schedules	`setSchedule`	Run a query or refresh a dashboard on a schedule
Schedules	`deleteSchedule`	Stop the schedule of a query or a dashboard
Account	`getUsage`	Check current billing-period credit usage

Resources

Resource	Description
`query-engine-writing-efficient-queries`	Performance and cost best practices for DuneSQL
`query-engine-functions-and-operators`	DuneSQL function/operator reference

Server Details

Server name: dune
Remote MCP URL: https://api.dune.com/mcp/v1
Tagline: Query, analyze, and visualize onchain data from Dune directly inside your MCP-compatible AI client.
Primary use cases:
- Discover datasets and docs relevant to a protocol, contract, or chain
- Create, update, execute, and troubleshoot Dune SQL queries
- Turn query results into charts/tables/counters without leaving your chat
- Create and manage full dashboards from natural language prompts
- Materialize query results into reusable tables and keep them fresh on a schedule
- Track account credit usage while iterating on analysis

Prompt Examples

Try prompts like these in your MCP-enabled client:

“Find the best Dune table for tracking Uniswap v3 swap volume on Ethereum, then create and run a daily volume query for the last 90 days.”
“I have contract 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48. Find decoded tables, build a weekly transfer count query, execute it, and show the top 20 recipient wallets.”
“Review query 1234567, optimize it for lower scan cost, update it in place, run it, and summarize result quality and execution credits used.”
“Generate a visualization from my latest execution results: a line chart of daily active addresses and a counter for total unique users.”
“Create a dashboard showing Ethereum activity in the past 30 days — include daily transactions, active addresses, and gas usage.”
“Update my existing dashboard to add a new chart showing weekly DEX volume by protocol.”
“Materialize my daily active addresses query into a table and refresh it every hour, then list my materialized views to confirm.”

Connection Details

Transport

Protocol: Remote MCP over Streamable HTTP
Endpoint: https://api.dune.com/mcp/v1
Interaction pattern:
- POST /mcp/v1 for MCP requests
- GET /mcp/v1 for stream resumption/event replay

OAuth 2.0 details

Authorization server issuer: https://dune.com/oauth/mcp
Discovery metadata: https://dune.com/.well-known/oauth-authorization-server/oauth/mcp
Authorization endpoint: https://dune.com/oauth/mcp/authorize
Token endpoint: https://dune.com/oauth/mcp/token
Dynamic client registration endpoint: https://dune.com/oauth/mcp/register
JWKS endpoint: https://dune.com/oauth/mcp/jwks.json
Grant types: authorization_code, refresh_token
Client auth at token endpoint: none (public clients)
PKCE: required (S256)
Scope: mcp:dune:full
Resource parameter for authorization requests: https://api.dune.com

Troubleshooting

OAuth invalid_request on authorize: Verify required params (client_id, redirect_uri, state, code_challenge, code_challenge_method=S256, resource=https://api.dune.com).
OAuth unsupported_grant_type on token: Use only authorization_code or refresh_token.
OAuth invalid_grant on token exchange: Ensure your code_verifier matches the original PKCE challenge and redirect_uri exactly matches the authorize request.
Unauthorized from MCP endpoint: Sign in again with your Dune account. In a headless environment, check that the x-dune-api-key header has a valid key.
Codex Transport closed during long polls: Increase MCP tool timeout (for example tool_timeout_sec = 300) and restart the session if the transport already closed.

Dune Skills Repository

Agent Skills for Dune — portable instruction packages that teach AI agents how to work with blockchain data using the Dune CLI.

Dune CLI & Skills Docs

Learn how to use the Dune CLI and Agent Skills as an alternative to MCP for terminal-native AI workflows.

Privacy and Support

Privacy policy: https://dune.com/privacy
Support: support@dune.com

Use Cases

Data Hub

Data API

Agents

Transform your Data

BI Visualization Tools

Dune Datashare

Setup and Usage

Authentication

Setup examples

Claude Code

Claude Desktop

OpenCode

Codex

Cursor

Headless and CI environments

Tools and Resources Inventory

Tools

Resources

Server Details

Prompt Examples

Connection Details

Transport

OAuth 2.0 details

Troubleshooting

Dune Skills Repository

Dune CLI & Skills Docs

Privacy and Support

​Setup and Usage

​Authentication

​Setup examples

​Claude Code

​Claude Desktop

​OpenCode

​Codex

​Cursor

​Headless and CI environments

​Tools and Resources Inventory

​Tools

​Resources

​Server Details

​Prompt Examples

​Connection Details

​Transport

​OAuth 2.0 details

​Troubleshooting

​Related Resources

Dune Skills Repository

Dune CLI & Skills Docs

​Privacy and Support

Setup and Usage

Authentication

Setup examples

Claude Code

Claude Desktop

OpenCode

Codex

Cursor

Headless and CI environments

Tools and Resources Inventory

Tools

Resources

Server Details

Prompt Examples

Connection Details

Transport

OAuth 2.0 details

Troubleshooting

Related Resources

Privacy and Support