MCP setup

ether.fi Catalog MCP

Connect AI agents to ether.fi dataset metadata, dashboards, freshness context, and query-planning guidance.

What it does

Find the right ether.fi dataset or dashboard.
Check freshness context and caveats before reporting or querying.
Plan safer DuneSQL with documented caveats and table semantics.
Use Dune MCP for execution, saved queries, charts, and dashboards.

Recommended setup

Before you install: uvx is required. DUNE_API_KEY is needed only for live Dune-backed tools.

Install command

uvx --from git+https://github.com/henrystats/etherfi-data-catalog.git etherfi-catalog-mcp

Install Dune MCP separately using Dune’s official instructions.
Use ether.fi Catalog MCP for dataset semantics, dashboard discovery, freshness context, and query planning.
Use Dune MCP for execution, saved queries, charts, and dashboards.
Use local stdio via uvx. Keep real credentials in private local config.
Do not put a shared team key in the repo.

Client configs

Codex config

Codex TOML

[mcp_servers.etherfi-catalog]
command = "uvx"
args = [
  "--from",
  "git+https://github.com/henrystats/etherfi-data-catalog.git",
  "etherfi-catalog-mcp",
]
enabled = true
startup_timeout_sec = 60
tool_timeout_sec = 120

[mcp_servers.etherfi-catalog.env]
DUNE_API_KEY = "your_dune_api_key_here"

Claude Desktop config

Claude JSON

{
  "mcpServers": {
    "etherfi-catalog": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/henrystats/etherfi-data-catalog.git",
        "etherfi-catalog-mcp"
      ],
      "env": {
        "DUNE_API_KEY": "your_dune_api_key_here"
      }
    }
  }
}

Use placeholders in examples. Put real credentials only in private local config.
Codex may use the global config at /Users/<user>/.codex/config.toml.
Claude Desktop typically uses a JSON MCP server config.
After editing MCP config, fully restart or reload the client.

Test it works

Metadata-only test

Use etherfi-catalog MCP only. Search datasets for "cash events", get details for the best match, and get the catalog health summary. Do not make live Dune calls.

Dashboard test

Use etherfi-catalog MCP only. Search dashboards for "cash" and summarize the best match. Do not make live Dune calls.

Planning test

Use etherfi-catalog MCP only. Plan a Dune query for weekly USDC cashback volume on ether.fi Cash. Do not execute live.

How to use with Dune MCP

Ask ether.fi Catalog MCP which dataset, dashboard, or freshness context applies.
Use Dune MCP to execute queries, create saved queries, build charts, or update dashboards.
Keep caveats and freshness notes in query descriptions.
Use live ether.fi tools only when needed and with narrow filters.

Live Dune-backed tools

Live calls require DUNE_API_KEY in the etherfi-catalog env block and may consume Dune credits. Use summary mode and narrow date, token, chain, or address filters.

Troubleshooting

If MCP does not load, confirm uvx works in your shell.
If Codex cannot see new config, restart Codex.
If live calls fail, confirm DUNE_API_KEY is under the etherfi-catalog env block.
On Apple Silicon, if uvx fails with /usr/local/bin/git ... Bad CPU type in executable, prefer /opt/homebrew/bin/git or /usr/bin/git.
If metadata works but live calls fail, the key may not be reaching the MCP runtime.