io.github.seob717/redash-mcp

redash-mcp

English | 한국어 | 日本語

MCP server that connects Redash to Claude, Cursor, Gemini CLI, Codex, and any MCP client — query data, build charts and dashboards, and run SQL with natural language.

Install · Tools · Env · Examples · Troubleshooting · Privacy

What's new in 3.5

• create_visualization — create line / column / area / pie / scatter charts or counters on a saved query. If the query has been run, column names are checked against its latest result, so a typo returns an error instead of an empty chart.
• Dashboard auto-layout — add_widget places new widgets below existing ones; half-width widgets pair up side by side (previously they all overlapped at the top-left).

Full history: Releases

Why redash-mcp?

Built for letting an LLM touch production data safely:

• 🛡️ SQL Safety Guard — blocks DROP/TRUNCATE/ALTER and DELETE/UPDATE without WHERE; strict/warn/off modes, PII detection, and auto-LIMIT.
• 🧠 BIRD Smart Query — analyzes the question, auto-selects tables, and guides SQL generation (BIRD text-to-SQL). Optional Claude Haiku fallback.
• 📊 End-to-end — query, save, chart, dashboards, and alerts — 25 tools.
• ⚡ One-command setup — npx redash-mcp setup configures Claude Desktop / Claude Code / Cursor / Gemini CLI / Codex CLI.
• 🔒 Fully local — talks directly to your Redash. API key and results never leave your machine.

Installation

Requirements: Node.js 20+ and a Redash API key (Redash → Profile → Edit Profile → API Key).

npx redash-mcp setup

The wizard configures any combination of Claude Desktop, Claude Code, Cursor, Gemini CLI, and Codex CLI.

Alternatively, install Node.js, Claude Desktop, and the MCP config in one go:

curl -fsSL https://raw.githubusercontent.com/seob717/redash-mcp/main/install.sh | bash

Manual setup

• Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor — ~/.cursor/mcp.json (create it if missing)

{
  "mcpServers": {
    "redash-mcp": {
      "command": "npx",
      "args": ["-y", "redash-mcp"],
      "env": {
        "REDASH_URL": "https://your-redash-instance.com",
        "REDASH_API_KEY": "your_api_key_here"
      }
    }
  }
}

Fully quit and restart Claude Desktop after saving.

Claude Code

claude mcp add --scope user redash-mcp \
  -e REDASH_URL=https://your-redash-instance.com \
  -e REDASH_API_KEY=your_api_key_here \
  -- npx -y redash-mcp

Gemini CLI

gemini mcp add -s user \
  -e REDASH_URL=https://your-redash-instance.com \
  -e REDASH_API_KEY=your_api_key_here \
  redash-mcp npx -y redash-mcp

Codex CLI

codex mcp add redash-mcp \
  --env REDASH_URL=https://your-redash-instance.com \
  --env REDASH_API_KEY=your_api_key_here \
  -- npx -y redash-mcp

Tools

SQL Safety Guard

Applies to ad-hoc SQL run through run_query. Saved queries executed with get_query_result are not checked, so give the Redash data source a read-only DB account.

• Always blocked (unless REDASH_SAFETY_MODE=off): DROP, TRUNCATE, ALTER TABLE, GRANT/REVOKE, DELETE/UPDATE without WHERE
• Warned (warn) / blocked (strict): SELECT *, queries without WHERE or LIMIT, PII column access
• Auto-LIMIT: appends LIMIT N when REDASH_AUTO_LIMIT is set

Details: docs/sql-safety-guard.md. Query results are also cached in memory (see REDASH_MCP_CACHE_* below).

Environment Variables

Usage Examples

Just ask in natural language:

• "How many new users signed up this month?" → smart_query picks the tables → run_query
• "What percentage of last week's new users made a purchase?" → smart_query guides the JOIN → run_query
• "Create an alert when daily signups drop below 100" → create_alert

Build a dashboard: "Save a monthly revenue query, chart it as a line, and put it on a new Revenue dashboard."

1. create_query — save "Monthly Revenue"
2. get_query_result — run it once so the chart columns can be checked
3. create_visualization — type: "line", x_column: "month", y_columns: ["revenue"]
4. create_dashboard — create "Revenue"
5. add_widget — place the chart; more widgets stack below or pair side by side

Troubleshooting

Development

npm install
npm run dev     # run from source (tsx)
npm test        # vitest
npm run build   # typecheck + bundle to dist/

Privacy Policy

redash-mcp is a local MCP server that talks directly to your Redash instance. No intermediate servers are involved.

We do not sell or share user data with third parties.

Retention: config files stay in ~/.redash-mcp/ until you delete them; the query cache is in-memory and cleared on shutdown; the schema cache is in-memory with a 10-minute TTL.

Contact: inquiries and security reports via GitHub Issues.

Disclaimer

redash-mcp is an unofficial, community-built integration and is not affiliated with, endorsed by, or sponsored by Redash. "Redash" is a trademark of its respective owners and is used here only to describe compatibility. This project communicates with Redash solely through its public REST API.

License

MIT