# Dune Analytics MCP > Dune Analytics Web3 SQL Analytics API lets your agent run complex SQL queries against live, historical data from major blockchains like Ethereum, Solana, and Polygon. You execute queries via natural conversation, track their status, retrieve the raw results, or cancel them if they take too long. ## Overview - **Category:** data-analytics - **Price:** Free - **Tags:** web3, sql, blockchain-data, ethereum, crypto-analytics ## Description Need to analyze on-chain metrics without opening a browser? This MCP connects your agent directly to Dune Analytics, letting you query massive blockchain datasets using SQL right from your preferred AI client. You don't have to build custom connectors for every chain; just talk to it and get the data. Your agent handles everything: running complex queries, waiting for results, fetching the final tables, and even killing a runaway job if needed. Because this connection is hosted on Vinkius, you connect once from your AI client and gain access to all of its capabilities. This means deep crypto research or financial analysis becomes a simple conversation. ## Tools ### cancel_execution Stops an ongoing query job immediately using its unique execution ID. ### execute_query Starts a new data analysis job by running a specific Dune query ID with optional parameters, returning a trackable ID. ### get_execution_results Retrieves the full set of data rows from an execution that has already finished successfully. ### get_execution_status Checks and reports the current state (pending, complete, or failed) of a running query job ID. ## Prompt Examples **Prompt:** ``` Execute Dune query ID 1234567 with parameters for the last 7 days. ``` **Response:** ``` I've started the execution for query 1234567. The execution ID is '01J8X...'. I will monitor the status for you. ``` **Prompt:** ``` Check the status of my Dune execution 01J8X9Z... ``` **Response:** ``` The execution 01J8X9Z... is currently 'QUERY_STATE_COMPLETED'. Would you like me to fetch the results now? ``` **Prompt:** ``` Fetch the results for execution ID 01J8X9Z... and summarize the top 5 holders. ``` **Response:** ``` I've retrieved the data. Based on the results, the top 5 holders are: 1) 0xabc... with 500 ETH, 2) 0xdef... with 450 ETH... ``` ## Capabilities ### Run custom SQL queries Start an execution job by providing a specific Dune query ID along with any required parameters. ### Monitor query status Check the current state of any running or queued query, seeing if it's pending, complete, or failed. ### Fetch raw data results Pull the full set of data rows from a completed query execution for immediate analysis. ### Stop runaway queries Cancel any ongoing or unnecessary query job to save API credits and clean up resources. ## Use Cases ### Tracking Whale Movements A researcher wants to know which wallets moved the most ETH last week. They ask their agent, and it uses `execute_query` with specific parameters for the date range. The agent then waits using `get_execution_status` until the data is ready, finally calling `get_execution_results` so they can summarize the top holders. ### Checking Protocol Health A developer needs to verify if a specific DeFi protocol's liquidity pool is reporting zero value. They ask their agent to run a predefined query ID and use `get_execution_status` repeatedly until the data returns, confirming the current on-chain state. ### Running Multi-Step Reports A financial analyst needs three different metrics (NFT volume, DAO treasury size, gas fee trends). They ask their agent to run these three separate queries sequentially and use `get_execution_results` for each one, compiling a single report in the chat window. ### Killing Stale Jobs An analyst accidentally runs an extremely broad query that hangs. Instead of waiting forever, they tell their agent to use `cancel_execution`, immediately freeing up resources and allowing them to re-run a more targeted job. ## Benefits - Stop leaving your workspace. You get to pull the latest DeFi, NFT, or DAO metrics without ever needing to open a separate dashboard. - Manage time and credits by using the `cancel_execution` tool. If a query stalls, you can stop it instantly instead of waiting minutes for nothing. - Get data right when you need it. The agent first uses `execute_query`, then polls with `get_execution_status`, ensuring you only retrieve results when they are actually ready. - Deep dive into multiple chains. This MCP covers Ethereum, Solana, Polygon, and more, meaning one connection handles all your Web3 data needs. - Analyze raw tables immediately. Once the job is done, `get_execution_results` pulls the entire dataset directly to your agent for visualization or scripting. ## How It Works The bottom line is, you initiate an asynchronous process, track its state, and then grab the resulting data without manually managing any web dashboard. 1. You tell your agent which Dune query you want to run, providing the necessary ID and parameters. 2. The system starts the execution and gives you a unique ID that tracks the job's progress. 3. Your agent monitors this status using the ID until it reports 'COMPLETED,' at which point it retrieves the full dataset. ## Frequently Asked Questions **How do I retrieve the actual data rows from a query?** First, use `execute_query` to start the process and get an `execution_id`. Once `get_execution_status` shows the state is completed, use `get_execution_results` with that ID to fetch the data. **Can I stop a query that is taking too long to run?** Yes. You can use the `cancel_execution` tool by providing the active `execution_id`. This will immediately interrupt the ongoing query on Dune's servers. **How do I pass parameters like dates or addresses to my Dune query?** When calling `execute_query`, use the `query_parameters` field. It accepts a JSON string (e.g., '{"address": "0x...", "limit": 10}'). The agent will parse this and apply it to your SQL execution. **How do I authenticate my Dune Analytics account before running an `execute_query`?** You must set up your connection using a valid Dune API Key. This key authorizes your AI client to run queries and tracks all usage against your personal quota. **What should I do if the `get_execution_status` reports that my query has failed?** A 'FAILED' status means Dune encountered an error, often due to incorrect SQL syntax or resource limits. You need to inspect the returned logs and adjust your query before retrying. **Is there a limit to how frequently I can use `execute_query`?** Yes, Dune enforces API rate limits and quota restrictions based on your plan type. Always check your usage dashboard within the Vinkius Marketplace to prevent service interruptions. **When should I call `get_execution_status` before attempting to use `get_execution_results`?** You must verify the status first. Calling `get_execution_status` ensures the query has reached 'COMPLETED' before your agent attempts to retrieve data via `get_execution_results`. **How does the API handle massive amounts of data retrieved by `get_execution_results`?** The MCP is built to manage large result sets, but you should process them in chunks or stream them through your agent. Loading millions of rows at once can overwhelm local memory.