holon-run/dune-mcp-skill

Dune MCP Skill

Use this skill to run Dune MCP operations through uxc.

Reuse the uxc skill for shared protocol discovery, output parsing, and generic auth/binding flows.

Prerequisites

• uxc is installed and available in PATH.
• Network access to https://api.dune.com/mcp/v1.
• Dune API key is available for authenticated calls.

Core Workflow

1. Confirm endpoint and protocol with help-first probing:
   • uxc https://api.dune.com/mcp/v1 -h
2. Configure credential/binding for repeatable auth:
   • uxc auth credential set dune-mcp --auth-type api_key --header "x-dune-api-key={{secret}}" --secret-env DUNE_API_KEY
   • uxc auth credential set dune-mcp --auth-type api_key --header "x-dune-api-key={{secret}}" --secret-op op://Engineering/dune/api-key
   • uxc auth binding add --id dune-mcp --host api.dune.com --path-prefix /mcp/v1 --scheme https --credential dune-mcp --priority 100
3. Use fixed link command by default:
   • command -v dune-mcp-cli
   • If missing, create it: uxc link dune-mcp-cli https://api.dune.com/mcp/v1
   • dune-mcp-cli -h
4. Inspect operation schema before execution:
   • dune-mcp-cli searchTables -h
   • dune-mcp-cli searchTablesByContractAddress -h
   • dune-mcp-cli createDuneQuery -h
   • dune-mcp-cli executeQueryById -h
   • dune-mcp-cli getExecutionResults -h
5. Prefer read/discovery operations first, then query creation or credit-consuming execution.

Capability Map

• Discovery:
  • searchDocs
  • searchTables
  • listBlockchains
  • searchTablesByContractAddress
• Query lifecycle:
  • createDuneQuery
  • getDuneQuery
  • updateDuneQuery
  • executeQueryById
  • getExecutionResults
• Analysis helpers:
  • generateVisualization
  • getTableSize
  • getUsage

Recommended Usage Pattern

1. Find the right table first:
   • dune-mcp-cli searchTables query='uniswap swaps'
   • dune-mcp-cli searchTablesByContractAddress contractAddress=0x...
2. Prefer higher-level spell tables when they already expose the metrics you need.
3. Keep SQL partition-aware:
   • use block_date, evt_block_date, or another partition/date column in WHERE
4. Create a temporary query only after confirming table choice and date range.
5. Execute and fetch results by execution ID.

Guardrails

• Keep automation on JSON output envelope; do not rely on --text.
• Parse stable fields first: ok, kind, protocol, data, error.
• Use dune-mcp-cli as default command path.
• dune-mcp-cli <operation> ... is equivalent to uxc https://api.dune.com/mcp/v1 <operation> ....
• Discovery operations are read-only:
  • searchDocs
  • searchTables
  • listBlockchains
  • searchTablesByContractAddress
  • getDuneQuery
  • getExecutionResults
  • getTableSize
  • getUsage
• Require explicit user confirmation before credit-consuming or state-changing operations:
  • createDuneQuery
  • updateDuneQuery
  • executeQueryById
  • generateVisualization
• Be careful with privacy:
  • confirm before switching a query from private to public
  • temporary queries can still be visible; inspect is_private and is_temp
• key=value input now supports automatic type conversion for numeric MCP arguments.
• Numeric IDs can be passed directly with key=value, for example:
  • query_id=6794106
  • queryId=6794106
• Positional JSON is still useful for nested objects or when mixing string and numeric fields precisely:
  • {"executionId":"01...","timeout":90,"limit":20}
• For SQL passed via key=value, wrap the whole SQL string in double quotes so inner SQL single quotes survive shell parsing.
• If listBlockchains returns a Dune-side schema/facet error, fall back to searchTables with blockchains filters.

Tested Real Scenario

The following flow was exercised successfully through uxc:

• discover table: uniswap.uniswapx_trades
• create temporary query for Base daily volume
• execute query
• fetch results

The successful SQL shape was:

SELECT block_date,
       ROUND(SUM(amount_usd), 2) AS daily_volume_usd,
       COUNT(*) AS trades
FROM uniswap.uniswapx_trades
WHERE blockchain = 'base'
  AND block_date >= date_add('day', -7, CURRENT_DATE)
GROUP BY 1
ORDER BY 1 DESC
LIMIT 7

References

• Invocation patterns:
  • references/usage-patterns.md