Redash MCP Server

Model Context Protocol (MCP) server for integrating Redash with AI assistants like Claude.

Features

• Connect to Redash instances via the Redash API
• List available queries and dashboards as resources
• Execute queries and retrieve results
• Execute saved parameterized queries with typed values and saved defaults
• Create and manage queries (create, update, archive)
• Manage query parameters, dashboard parameters, and widget parameter mappings
• Inspect and update dashboard widget layouts and grid positions
• List data sources for query creation
• Get dashboard details and visualizations
• Update chart visualization options with Redash chart-specific settings

Prerequisites

• Node.js (v22.13 or later)
• Corepack (included with Node.js 22; it selects the pnpm version pinned in package.json)
• Access to a Redash instance
• Redash API key

Environment Variables

The server requires the following environment variables:

• REDASH_URL: Your Redash instance URL (e.g., https://redash.example.com)
• REDASH_API_KEY: Your Redash API key

Optional variables:

• REDASH_TIMEOUT: Timeout for API requests in milliseconds (default: 30000)
• REDASH_MAX_RESULTS: Maximum number of results to return (default: 1000)
• REDASH_EXTRA_HEADERS: Extra HTTP headers to include with every Redash request. Accepts either a JSON object string or a semicolon/comma-separated list of key=value pairs.
• REDASH_SOCKS_PROXY: SOCKS proxy URL for routing requests through a proxy (e.g., socks5h://localhost:1080). Use socks5h:// (with h) to delegate DNS resolution to the proxy, which is required for internal hostnames that don't resolve on the local machine.
• MCP_TRANSPORT: MCP transport to use. Supported values are stdio, http, and streamable-http (default: stdio).
• MCP_HTTP_HOST: Host for Streamable HTTP mode (default: 127.0.0.1).
• MCP_HTTP_PORT: Port for Streamable HTTP mode (default: 3000).
• MCP_HTTP_PATH: Streamable HTTP endpoint path (default: /mcp).
• MCP_HTTP_ALLOWED_HOSTS: Comma-separated Host header allowlist for Streamable HTTP mode. Values are hostnames without a scheme, port, path, or wildcard.
• MCP_HTTP_ALLOWED_ORIGINS: Comma-separated browser Origin hostname allowlist. Values use the same hostname-only format and also control CORS responses. Set an empty value to reject every request that includes an Origin header.
• OpenTelemetry variables: optional; see OpenTelemetry observability for concrete OTLP and Prometheus configurations.

Examples:

JSON (recommended):

Copy code
REDASH_EXTRA_HEADERS='{"CF-Access-Client-Id":"<client_id>","CF-Access-Client-Secret":"<client_secret>"}'

Key/value list:

Copy code
REDASH_EXTRA_HEADERS=CF-Access-Client-Id=<client_id>;CF-Access-Client-Secret=<client_secret>

Notes:

• The Authorization header is managed by the server (Key <REDASH_API_KEY>) and cannot be overridden.
• All extra headers are added to every request made to Redash.

Installation

1. Clone this repository:

   bashCopy code
   git clone https://github.com/suthio/redash-mcp.git
   cd redash-mcp
   

2. Enable Corepack and install dependencies:

   bashCopy code
   corepack enable
   pnpm install
   

3. Create a .env file with your Redash configuration:

   Copy code
   REDASH_URL=https://your-redash-instance.com
   REDASH_API_KEY=your_api_key
   # Optional: Cloudflare Access (or other gateway) headers
   # REDASH_EXTRA_HEADERS='{"CF-Access-Client-Id":"<client_id>","CF-Access-Client-Secret":"<client_secret>"}'
   

4. Build the project:

   bashCopy code
   pnpm run build
   

5. Start the server:

   bashCopy code
   pnpm start
   

   The default transport is stdio, which is the mode expected by most desktop MCP clients. The stdio entrypoint accepts both 2025-era MCP clients and clients that negotiate the current protocol.

Usage with Claude for Desktop

To use this MCP server with Claude for Desktop, configure it in your Claude for Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration (edit paths as needed):

jsonCopy code
{
  "mcpServers": {
    "redash": {
      "command": "npx",
      "args": [
         "-y",
         "@suthio/redash-mcp"
      ],
      "env": {
        "REDASH_API_KEY": "your-api-key",
        "REDASH_URL": "https://your-redash-instance.com"
      }
    }
  }
}

Streamable HTTP Transport

The server can also run as a stateless Streamable HTTP MCP server. The HTTP entrypoint is a Hono application served by @hono/node-server; environment variables configure the listener:

bashCopy code
REDASH_URL=https://your-redash-instance.com \
REDASH_API_KEY=your_api_key \
MCP_TRANSPORT=http \
pnpm start

This starts POST http://127.0.0.1:3000/mcp by default. CLI flags override environment variables:

bashCopy code
REDASH_URL=https://your-redash-instance.com \
REDASH_API_KEY=your_api_key \
pnpm start --transport http --host 127.0.0.1 --port 3333 --path /mcp

For a non-local bind behind an authenticated, TLS-terminating reverse proxy, explicitly configure which request hosts and browser origins may reach the server. The equivalent CLI options are --allowed-hosts and --allowed-origins.

bashCopy code
REDASH_URL=https://redash.example.com \
REDASH_API_KEY=your_api_key \
MCP_TRANSPORT=http \
MCP_HTTP_HOST=0.0.0.0 \
MCP_HTTP_ALLOWED_HOSTS=mcp.example.com \
MCP_HTTP_ALLOWED_ORIGINS=app.example.com \
pnpm start

Host and Origin matching is case-insensitive and port-agnostic. For example, allowing app.example.com accepts the browser Origin https://app.example.com:8443. In HTTP mode, binding MCP_HTTP_HOST to a non-local address fails at startup unless both allowlist settings are explicitly present.

Host and Origin allowlists protect against DNS rebinding and unwanted browser origins; they do not authenticate MCP clients. Do not expose the server listener directly to the internet. For https://mcp.example.com/mcp, keep the listener on a private network and require authentication at the reverse proxy or gateway.

HTTP mode is stateless: the server does not issue Mcp-Session-Id, does not provide a standalone GET SSE stream, and handles each POST /mcp with a fresh MCP server instance. Both current MCP clients and 2025-era Streamable HTTP clients use that same URL. GET /mcp and DELETE /mcp return 405 Method Not Allowed.

The default bind is localhost-only (127.0.0.1) with Host and Origin protection. Browser requests from allowed origins receive CORS response headers; other origins are rejected with 403 Forbidden.

GET http://127.0.0.1:3000/healthz returns 200 OK with the body ok for lightweight health checks. It uses the same Host and Origin allowlists as the MCP endpoint and does not contact Redash. If MCP_HTTP_PATH=/healthz, that URL remains the MCP endpoint and the standalone health check is disabled with a startup warning.

The CLI handles SIGINT and SIGTERM gracefully. For example, docker stop sends SIGTERM; the server closes active MCP streams and then waits for the HTTP listener to stop before the process exits.

OpenTelemetry observability

Operators use this integration to follow one MCP operation from the client, through this server, to Redash, and to alert on latency or process health. The CLI initializes OpenTelemetry automatically. With no exporter endpoint or exporter setting, it opens no telemetry network connection; application logs still go to stderr so stdio stdout remains reserved for MCP messages.

Choose the setup that matches the system reading the telemetry:

For example, this HTTP-mode command exports all signals over OTLP/HTTP and also lets Prometheus scrape the same listener:

bashCopy code
REDASH_URL=https://redash.example.com \
REDASH_API_KEY=your_api_key \
MCP_TRANSPORT=http \
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_METRICS_EXPORTER=otlp,prometheus \
pnpm start

curl http://127.0.0.1:3000/metrics

The server emits these signals:

The names and attributes visible in a trace backend are deliberately stable:

mcp.protocol.version records the negotiated revision in both stdio and stateless HTTP operations. mcp.server.session.duration applies to the long-lived stdio connection; HTTP mode is stateless, so its useful lifecycle measurement is mcp.server.operation.duration. Both histograms use the MCP-recommended explicit latency buckets.

SEP-414 traceparent, tracestate, and baggage values in MCP request _meta are accepted. The extracted MCP client context becomes the MCP server span's parent, while the HTTP transport span is linked to it. Logs emitted while the tool runs carry the MCP span's trace_id and span_id.

Application log messages always go to stderr. When OTel Logs is configured, the same message is exported with its structured fields; those fields are not printed to stderr. A compatible stdio MCP client also receives the message through notifications/message for backward compatibility. Stateless HTTP does not send those notifications because each POST uses a fresh server instance; use OTel Logs or stderr there.

Exporter settings

The OTLP exporters support gRPC, HTTP/protobuf, and HTTP/JSON:

Set the shared OTEL_EXPORTER_OTLP_PROTOCOL, or override it with OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, OTEL_EXPORTER_OTLP_METRICS_PROTOCOL, and OTEL_EXPORTER_OTLP_LOGS_PROTOCOL. The corresponding standard endpoint, header, certificate, compression, and timeout variables are passed to the OpenTelemetry exporters.

An endpoint enables its signal. You can make the decision explicit with OTEL_TRACES_EXPORTER=otlp, OTEL_METRICS_EXPORTER=otlp, and OTEL_LOGS_EXPORTER=otlp, or disable one with none. For example, this keeps logs on stderr while sending traces and metrics:

bashCopy code
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.internal:4318
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=none

OTEL_SDK_DISABLED=true disables every telemetry signal. Invalid telemetry settings or an unavailable exporter produce a warning on stderr but do not stop MCP or Redash requests. Application configuration errors such as a missing REDASH_API_KEY still fail startup.

Prometheus endpoint and content safety

In HTTP mode, the embedded /metrics route uses the same Host allowlist as /mcp. If MCP_HTTP_PATH=/metrics, the server keeps that URL for MCP, traces it as POST /metrics, and disables the embedded Prometheus route with a warning. Set OTEL_EXPORTER_PROMETHEUS_HOST or OTEL_EXPORTER_PROMETHEUS_PORT to use a separate listener instead. A separate listener is not protected by the MCP Host/Origin checks, so bind it to 127.0.0.1 or protect it at the network layer.

Safe operation metadata is always available. Content that may contain Redash data requires an explicit opt-in:

The option uses the GenAI instrumentation name because the OpenTelemetry MCP conventions model a tool call as a GenAI-compatible execute_tool operation. The Redash server does not perform model inference; it reuses the common gen_ai.tool.call.* attributes so an MCP call can be correlated with the agent that invoked it. Enable the option only when the trace and log backends are approved to retain Redash content.

Embedding the server in another Node.js process

Initialize telemetry before importing the main package so Node HTTP and Axios are patched before Redash requests begin:

tsCopy code
import {
  initializeTelemetry,
  shutdownTelemetry,
} from "@suthio/redash-mcp/telemetry";

await initializeTelemetry({ transport: "stdio" });
const { createRedashMcpServer } = await import("@suthio/redash-mcp");
const server = createRedashMcpServer();

// Connect and use the server, then flush exporters during application shutdown.
await server.close();
await shutdownTelemetry();

When the embedding process exposes MCP over HTTP at POST /redash-mcp, pass that exact route during telemetry initialization and identify the application protocol when creating the server:

tsCopy code
import {
  initializeTelemetry,
  shutdownTelemetry,
} from "@suthio/redash-mcp/telemetry";

await initializeTelemetry({ transport: "http", httpPath: "/redash-mcp" });
const { createRedashMcpServer } = await import("@suthio/redash-mcp");
const server = createRedashMcpServer({
  networkTransport: "tcp",
  networkProtocolName: "http",
  recordSession: false,
});

// Connect `server` to the embedding process's POST /redash-mcp transport.
await server.close();
await shutdownTelemetry();

Docker

Container images are published to GitHub Container Registry for both linux/amd64 and linux/arm64.

bashCopy code
docker run --rm -p 127.0.0.1:3000:3000 \
  -e REDASH_URL=https://your-redash-instance.com \
  -e REDASH_API_KEY=your_api_key \
  ghcr.io/suthio/redash-mcp:latest

The container runs Streamable HTTP internally on 0.0.0.0:3000, while the example publishes that port on the host's loopback interface only. Its default Host and Origin allowlists accept localhost access. When placing the container behind an authenticated reverse proxy or a private cluster service, set MCP_HTTP_ALLOWED_HOSTS and MCP_HTTP_ALLOWED_ORIGINS to the concrete DNS names used by clients. Published images are signed with keyless cosign.

Available Tools

Query Management

• list_queries: List all available queries in Redash
• get_query: Get details of a specific query
• create_query: Create a new query in Redash
• update_query: Update an existing query in Redash
• get_query_parameters: Inspect saved query parameter definitions
• update_query_parameters: Update saved query parameter definitions
• archive_query: Archive (soft-delete) a query
• list_data_sources: List all available data sources

Query Execution

• execute_query: Execute a query and return results, with optional maxAge
• execute_parameterized_query: Execute a saved parameterized query with type-aware value coercion, saved defaults, and optional maxAge
• execute_adhoc_query: Execute an ad-hoc query without saving it to Redash
• get_query_results_csv: Get query results in CSV format (supports optional refresh for latest data)

Schema Discovery

• get_schema: Get the schema of a data source, paginated by table

Use get_schema when an MCP client needs table and column names for writing a query. A caller can request a small page, inspect hasMore, and follow nextPage without loading the entire warehouse schema into this MCP server. For BigQuery, a configured location also allows the server to fetch only the requested tables.

Parameters: dataSourceId (required), page (default 1), pageSize (default 25, max 100), and search (optional case-insensitive substring match on table names; pagination applies to the filtered set). The response includes hasMore and nextPage for iterating through large schemas.

For example, to inspect tables in a BigQuery dataset named analytics_public on data source 7, call get_schema with {"dataSourceId":7,"pageSize":10,"search":"analytics_public."}. pageSize limits the number of tables in one response; it does not split the columns or nested field paths within a table. A wide table such as a GA4 event export is therefore returned with all of its field paths even when pageSize is 1.

Dashboard Management

• list_dashboards: List all available dashboards
• get_dashboard: Get dashboard details and visualizations
• get_dashboard_layout: Inspect widget positions, sizes, and visibility on a dashboard
• get_visualization: Get details of a specific visualization
• get_dashboard_parameters: Inspect dashboard parameter values and widget mappings
• update_dashboard_parameters: Update dashboard parameter values and order
• update_dashboard_layout: Move or resize multiple widgets in one call
• update_widget_layout: Move or resize a single widget
• get_widget_parameter_mappings: Inspect a widget's parameter mappings
• update_widget_parameter_mappings: Update a widget's parameter mappings

Visualization Management

• create_visualization: Create a new visualization for a query
• update_visualization: Update an existing visualization
• update_chart_visualization: Patch chart-specific options like globalSeriesType, columnMapping, seriesOptions, legend, and axis settings
• delete_visualization: Delete a visualization

Development

Run in development mode:

bashCopy code
pnpm run dev

Testing

Unit Tests

bashCopy code
pnpm test

E2E Tests

bashCopy code
pnpm run e2e:test

E2E tests use these default values (can be overridden with environment variables):

• REDASH_URL: https://demo.redash.io
• REDASH_API_KEY: test_api_key

Override example:

bashCopy code
REDASH_URL=https://your-instance.com REDASH_API_KEY=your_key pnpm run e2e:test

Manual Testing

bashCopy code
pnpm run inspector

Version History

• v1.1.0: Added query management functionality (create, update, archive)
• v1.0.0: Initial release

Maintainers

• @suthio
• @kahirokunn

License

MIT