dune-mcp-skill

Original：🇺🇸 English

Translated

1 scripts

Use Dune MCP through UXC for blockchain table discovery, SQL query creation/execution, execution result retrieval, and visualization with help-first schema inspection, explicit auth binding, and guarded credit-consuming operations.

4installs

Sourceholon-run/uxc

Added on2026-04-24

NPX Install

npx skill4agent add holon-run/uxc dune-mcp-skill

SKILL.md Content

View Translation Comparison →

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

Confirm endpoint and protocol with help-first probing:
- ```
uxc https://api.dune.com/mcp/v1 -h
```

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

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
```

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
```

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

Find the right table first:

dune-mcp-cli searchTables query='uniswap swaps'

dune-mcp-cli searchTablesByContractAddress contractAddress=0x...

Prefer higher-level
```
spell
```
tables when they already expose the metrics you need.
Keep SQL partition-aware:
- use
```
block_date
```
  ,
```
evt_block_date
```
  , or another partition/date column in
```
WHERE
```
Create a temporary query only after confirming table choice and date range.
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:

sql

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
```