redash-mcp

Expose the Redash API as an MCP (Model Context Protocol) server. Schema, column values, and code-to-label mappings are cached — in memory for schema and persistently on disk for metadata — so repeated lookups skip redundant Redash calls and the model can compose queries without re-exploring the database every time.

한국어 문서 / Korean README

Installation & Setup

npx (no installation required)

Add the following to ~/.mcp.json.

{
  "mcpServers": {
    "redash": {
      "command": "npx",
      "args": ["@seungje.jun/redash-mcp"],
      "env": {
        "REDASH_URL": "https://redash.example.com",
        "REDASH_API_KEY": "your-key"
      }
    }
  }
}

Build from source

git clone https://github.com/ninanung/redash-mcp.git
cd redash-mcp
npm install
npm run build

Add the following to ~/.mcp.json.

{
  "mcpServers": {
    "redash": {
      "command": "node",
      "args": ["/path/to/redash-mcp/dist/cli.js"],
      "env": {
        "REDASH_URL": "https://redash.example.com",
        "REDASH_API_KEY": "your-key"
      }
    }
  }
}

Restart Claude Code to activate the MCP tools.

Environment Variables

| Variable | Description | |----------|-------------| | REDASH_URL | Redash server URL (single-instance mode, required when REDASH_INSTANCES is unset) | | REDASH_API_KEY | Redash API Key (single-instance mode) | | REDASH_INSTANCES | (optional) JSON array for multi-instance mode. Example: [{"name":"prod","url":"...","api_key":"...","allowed_data_sources":[1,2]},{"name":"dev","url":"...","api_key":"..."}]. When set, pass instance: "prod" on any tool call to pick the target. Falls back to the first entry if instance is omitted. | | REDASH_ALLOWED_DS | (optional) Comma-separated list of allowed data source IDs (e.g. 1,3,7). When set, all other IDs are blocked and list_data_sources only returns allowed ones. | | REDASH_MCP_LOG | (optional) Log level: debug, info (default), warn, error, silent. Logs go to stderr to avoid corrupting the MCP stdio channel. | | REDASH_MCP_AUDIT_LOG | (optional) Audit log file path. Defaults to ~/.redash-mcp/audit.log. Set to off to disable. Each line is a JSON record with tool name, args, duration, status. | | REDASH_QUERY_TIMEOUT_MS | (optional) Default query timeout in ms (default 120000). Override per-call via execute_query's timeout_ms argument. | | REDASH_SUMMARIZE_THRESHOLD | (optional) Row count above which execute_query auto-summarizes results (per-column min/max/distinct/null + 10 sample rows). Default 500. save_csv disables auto mode. Override per call with summarize:"never". | | REDASH_MASK_COLUMNS | (optional) Column-name patterns to mask in result rows (comma-separated, * wildcard supported). Include builtin to also mask common PII columns (email, phone, SSN/RRN, password, token, card). Example: builtin,user_name,addr* | | REDASH_DEFAULT_FORMAT | (optional) Default result encoding for execute_query / execute_saved_query: json (default) or compact. A per-call format argument overrides it. | | REDASH_DEFAULT_MAX_ROWS | (optional) Default row cap for execute_query / execute_saved_query when the call passes no max_rows (default 1000). | | REDASH_RESULT_HINTS | (optional) Set to off to drop the trailing LLM guidance from query results ("IMPORTANT: include the executed SQL verbatim…", "To save this query, use save_query…"). Default: on. Useful when your own prompt governs presentation or save_query is not exposed. | | REDASH_METADATA_TTL_DAYS | (optional) Metadata cache TTL in days. When set, entries older than this are treated as cache misses by explore_column / find_mapping / get_schema and are re-fetched; get_cache output tags them [stale]. Unset = keep forever. |

Tools

| Tool | Description | |------|-------------| | list_data_sources | List available data sources | | self_test | Diagnostic check — verifies env vars, Redash connectivity, and schema access | | get_schema | Fetch table/column schema (keyword filter, cached) | | execute_query | Run SQL (only SELECT/WITH allowed; job polling handled automatically; auto-injects LIMIT max_rows — default 1000 — when the query has none; format: "compact" returns rows as arrays at about a quarter of the size) | | explain_query | Run EXPLAIN for a query without executing it — inspect cost / scan plan before a heavy run (engine-specific support) | | explore_column | Inspect unique values/counts and infer column types (supports multiple columns at once) | | sample_rows | Return a few raw rows from a table (default 5) to inspect real column values at a glance | | describe_table | Combined schema + sample rows for a single table | | find_table | Find tables by column name and/or table-name keyword (useful when locating join targets) | | join_hints | List other tables that share column names with the given table — candidate join keys | | find_mapping | Automatically find mapping tables for numeric code columns | | save_query | Save a SQL query to Redash (supports description and tags) | | update_query | Update name/query/description/tags of an existing saved query | | list_saved_queries | List queries already saved in Redash (supports search + data source filter) | | get_saved_query | Fetch SQL and metadata of a saved query by ID, including declared parameters (name, type, stored default, enum choices) and who last saved it | | execute_saved_query | Run a saved query by ID with optional parameters; omitted parameters fall back to the stored defaults, a p_ URL-style prefix is stripped, values are converted to the declared parameter type (text / number), unknown names are rejected with the accepted list, and the result echoes the parameter values actually used | | list_dashboards | List Redash dashboards (search supported) | | get_dashboard | Fetch widgets of a dashboard and the query IDs they reference | | get_cache | Read the metadata cache (column types/values, mapping tables, recommended tables) | | export_metadata_cache | Export the metadata cache to a JSON file (share across a team or back up) | | import_metadata_cache | Import a metadata cache from a JSON file (merge/replace modes) |

Usage Example

A typical natural-language flow, as orchestrated by the MCP client:

1. User: "Find me the orders table and show yesterday's revenue."
2. list_data_sources → pick the target data_source_id.
3. get_schema with keyword order → locate candidate tables/columns.
4. explore_column on status/type columns → understand enum values and infer types.
5. find_mapping on code columns (e.g. status_cd) → resolve numeric codes to labels.
6. execute_query → run the final SELECT and return rows.
7. (Optional) save_query → persist the SQL back to Redash.

Subsequent runs reuse the metadata cache, so step 4–5 often short-circuits via get_cache.

Safety & Constraints

• Read-only SQL: only statements starting with SELECT or WITH are allowed. DML/DDL keywords (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, MERGE, GRANT, REVOKE, CALL, EXEC, ...) are rejected even if buried inside a CTE. Multiple statements separated by semicolons are also blocked. Comments and string literals are stripped before the scan to prevent keyword-smuggling.
• Row-limit guardrail: execute_query auto-injects LIMIT max_rows (default 1000) when the query has no LIMIT, preventing accidental full-table scans from blowing up the model context. Override with the max_rows argument or include an explicit LIMIT in the SQL.
• CSV export: pass save_csv: "/path/to/out.csv" to execute_query to write the full result to disk instead of (or in addition to) returning it through the model context.
• Automatic schema recovery: if a query fails with a "table/column not found" style error, the schema cache for that data source is invalidated and refreshed. For a missing column, the actual columns of the tables referenced in FROM/JOIN are returned; for a missing table, up to 50 similarly named tables are suggested. Either way the model can fix the query in one retry.
• Compact output: format: "compact" (or REDASH_DEFAULT_FORMAT=compact) encodes columns/column_types as arrays and rows as arrays of values with no indentation. Row caps are announced in the notes ("Returned the first M rows" / "Returned the first M of N rows").
• Job polling: Redash async jobs are polled until completion; only the final result is returned to the client.
• No write API: the server does not expose any endpoint that mutates Redash state other than save_query (creating a new saved query).

Data Source Selection

• data_source_id is a required argument on every query-related tool (execute_query, get_schema, explore_column, find_mapping, save_query).
• Call list_data_sources first to discover available IDs; the MCP client is expected to pass the chosen ID explicitly.
• There is no implicit "default data source" — this is intentional, to avoid accidentally querying the wrong database when multiple sources are configured.
• Set REDASH_ALLOWED_DS=1,3,7 to restrict the server to specific data source IDs. Any other ID is rejected before hitting Redash, and list_data_sources / list_saved_queries return only the allowed subset.

Cache

• Schema cache: in-memory, kept alive while the server runs. Refreshed automatically when a query execution hits a table/column error. Manual refresh is available via refresh: true on get_schema, which also asks Redash to rebuild its own server-side schema cache (this is what picks up newly created tables). Every get_schema response starts with a status line: cached/fresh, table count, and fetch time.
• Metadata cache: persisted to ~/.redash-mcp/metadata-cache.json. Results from explore_column and find_mapping are stored automatically and reused on subsequent lookups. Keys are prefixed with ds<id>: so the same table name in different data sources never collides.

Cache Location & Reset

| Cache | Location | Reset | |-------|----------|-------| | Schema | in-memory (per server process) | restart the MCP server, or call get_schema with refresh: true | | Metadata | ~/.redash-mcp/metadata-cache.json | delete the file (rm ~/.redash-mcp/metadata-cache.json) — it will be recreated on the next write |

The metadata cache file is a plain JSON document — safe to inspect, edit, or back up manually.

License

MIT