Skip to main content
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, and generate visualizations in the same conversation. This is the fastest way to move from prompt to reliable onchain analysis.

​
Setup and Usage

​
Authentication

Dune MCP supports two authentication modes today:
  1. OAuth 2.0 (recommended for Browser agents or agents with access to the browser)
  2. Dune API key (recommended for environments with no access to a browser)

​
OAuth

Typically when setting up OAuth the agent just needs:
  • Name: Dune
  • url: https://api.dune.com/mcp/v1
When you add these details you will likely see your browser open up on the Dune Login page where upon successful login you will be taken back your Agent where you should be logged in and ready to go.

​
Api Key

You can authenticate with the MCP using your Dune Api Key
  • Header auth: x-dune-api-key: <dune-api-key>
  • Query auth (for clients that prefer URL auth): ?api_key=<dune_api_key>
Generally using the Header is preferred but some agents do now allow you to configure the Headers sent with MCP calls. In those cases you can pass the api key in the url query parameters.

​
Setup exampls

​
Claude Code

​
Oauth


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

​
API Key

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

​
Claude Desktop

​
OpenCode

​
Oauth

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

​
API Key

Connect opencode to Dune MCP

​
Codex

​
Oauth

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

# Login after adding the MCP
codex mcp login dune

​
API Key

codex mcp add dune_prod --url "https://api.dune.com/mcp/v1?api_key=<dune_api_key>"
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: Oauth 
{
  "mcpServers": {
    "dune": {
      "url": "https://api.dune.com/mcp/v1",
    }
  }
}
Api Key 
{
  "mcpServers": {
    "dune": {
      "url": "https://api.dune.com/mcp/v1",
      "headers": {
        "X-DUNE-API-KEY": "<api_key>"
      }
    }
  }
}

​
Tools and Resources Inventory

​
Tools

CategoryToolDescription
DiscoverysearchDocsSearch Dune docs for guides, examples, and API references
DiscoverysearchTablesFind tables by protocol, chain, category, or schema
DiscoverylistBlockchainsList indexed blockchains with table counts
DiscoverysearchTablesByContractAddressFind decoded event/call tables for a contract address
DiscoverygetTableSizeEstimate the data scanned by a query for one or more tables
Query LifecyclecreateDuneQueryCreate and save a new Dune query
Query LifecyclegetDuneQueryFetch SQL and metadata for an existing query
Query LifecycleupdateDuneQueryUpdate SQL, title, description, tags, or parameters
Query LifecycleexecuteQueryByIdExecute a saved query and return an execution ID
Query LifecyclegetExecutionResultsFetch status and results for a query execution
VisualizationgenerateVisualizationCreate charts, counters, and tables from query results
AccountgetUsageCheck current billing-period credit usage

​
Resources

ResourceDescription
query-engine-writing-efficient-queriesPerformance and cost best practices for DuneSQL
query-engine-functions-and-operatorsDuneSQL 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
    • Track account credit usage while iterating on analysis

​
Prompt Examples

Try prompts like these in your MCP-enabled client:
  1. “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.”
  2. “I have contract 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48. Find decoded tables, build a weekly transfer count query, execute it, and show the top 20 recipient wallets.”
  3. “Review query 1234567, optimize it for lower scan cost, update it in place, run it, and summarize result quality and execution credits used.”
  4. “Generate a visualization from my latest execution results: a line chart of daily active addresses and a counter for total unique users.”

​
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: Confirm valid auth (OAuth bearer token or Dune API 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.

​
Privacy and Support