npm package: @ryan4u/redash-mcp-server
Description: MCP server for Redash analytics integration - runnable via npx
Latest version: 1.0.0

# Redash MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)

MCP (Model Context Protocol) server for Redash API integration. Can be run directly via `npx` without installation.

## Features

- **60+ Tools**: Data sources, queries, dashboards, alerts, visualizations, widgets, and more
- **Dual Mode**: STDIO mode for single-user (Cursor, Claude Desktop) and HTTP mode for multi-user
- **No Installation Required**: Run directly with `npx`
- **TypeScript**: Built with TypeScript for type safety

## Quick Start

### 1. Get Your Redash API Key

Go to your Redash instance: **Settings → Account → API Key**

### 2. Configure Your AI Agent

#### Cursor IDE / Claude Desktop

```json
{
  "mcpServers": {
    "Redash analytics": {
      "command": "npx",
      "args": ["-y", "@ryan4u/redash-mcp-server", "--stdio"],
      "env": {
        "REDASH_API_KEY": "your-api-key-here",
        "REDASH_API_URL": "http://your-redash-instance:5000/api"
      }
    }
  }
}
```

#### Claude Code

```bash
claude mcp add redash-analytics \
  -e REDASH_API_KEY=your-api-key-here \
  -e REDASH_API_URL=http://your-redash-instance:5000/api \
  -- npx -y @yourname/redash-mcp-server --stdio
```

### 3. Run in HTTP Mode (Multi-user)

```bash
export REDASH_API_URL="http://your-redash-instance:5000/api"
export MCP_AUTH_TOKENS="token1,token2"
npx -y @yourname/redash-mcp-server --http
```

## Environment Variables

| Variable | Mode | Required | Default | Description |
|----------|------|----------|---------|-------------|
| `REDASH_API_KEY` | STDIO | Yes | — | Redash API key |
| `REDASH_API_URL` | Both | No | `http://localhost:5000/api` | Redash instance API URL |
| `REDASH_TIMEOUT` | Both | No | `30` | Request timeout in seconds (1–300) |
| `REDASH_MAX_RETRIES` | Both | No | `2` | Max retries on network errors (0–5) |
| `MCP_MODE` | Both | No | `stdio` | Server mode: `stdio` or `http` |
| `MCP_AUTH_TOKENS` | HTTP | Yes | — | Comma-separated MCP access tokens |
| `MCP_HOST` | HTTP | No | `127.0.0.1` | HTTP bind address |
| `MCP_PORT` | HTTP | No | `3000` | HTTP port number |
| `MCP_RATE_LIMIT` | HTTP | No | `60` | Max requests/min per IP |
| `MCP_SESSION_TIMEOUT` | HTTP | No | `1800` | Session TTL in seconds |
| `MCP_MAX_BODY_SIZE` | HTTP | No | `1048576` | Max request body in bytes |
| `LOG_LEVEL` | Both | No | `info` | Log level |

## Available Tools

### Data Sources (6)
- `list_data_sources` — List all available data sources
- `get_data_source` — Get data source details
- `get_data_source_schema` — Get table/column schema
- `test_data_source` — Test data source connection
- `pause_data_source` — Pause a data source
- `resume_data_source` — Resume a paused data source

### Queries (12)
- `list_queries` — List saved queries with pagination
- `get_query` — Get query details including SQL
- `search_queries` — Search queries by name/description
- `create_query` — Create a new query
- `update_query` — Update query name, description, or SQL
- `archive_query` — Archive a query
- `refresh_query` — Force refresh query results
- `fork_query` — Fork a query
- `list_my_queries` — List my queries
- `list_recent_queries` — List recent queries
- `list_archived_queries` — List archived queries
- `list_query_tags` — List all query tags

### Query Execution (4)
- `execute_query` — Execute a saved query
- `execute_adhoc_query` — Execute an ad-hoc SQL query
- `get_query_result` — Get cached query result
- `get_job_status` — Get background job status

### Dashboards (10)
- `list_dashboards` — List dashboards with pagination
- `get_dashboard` — Get dashboard with widgets
- `create_dashboard` — Create a new dashboard
- `update_dashboard` — Update dashboard name or tags
- `archive_dashboard` — Archive a dashboard
- `fork_dashboard` — Fork a dashboard
- `share_dashboard` — Enable public dashboard access
- `unshare_dashboard` — Disable public dashboard access
- `list_my_dashboards` — List my dashboards
- `list_dashboard_tags` — List all dashboard tags

### Widgets (2)
- `add_widget` — Add a widget to a dashboard
- `remove_widget` — Remove a widget from a dashboard

### Visualizations (3)
- `create_visualization` — Create a visualization for a query
- `update_visualization` — Update a visualization
- `delete_visualization` — Delete a visualization

### Alerts (9)
- `list_alerts` — List all alerts
- `get_alert` — Get alert details
- `create_alert` — Create an alert
- `update_alert` — Update an alert
- `delete_alert` — Delete an alert
- `mute_alert` — Mute an alert
- `unmute_alert` — Unmute an alert
- `list_alert_subscriptions` — List alert subscriptions
- `create_alert_subscription` — Subscribe a destination to an alert
- `delete_alert_subscription` — Remove an alert subscription

### Users (2)
- `list_users` — List users
- `get_user` — Get user details

### Favorites (6)
- `favorite_query` / `unfavorite_query` — Add/remove query from favorites
- `favorite_dashboard` / `unfavorite_dashboard` — Add/remove dashboard from favorites
- `list_favorite_queries` — List favorite queries
- `list_favorite_dashboards` — List favorite dashboards

### Query Snippets (5)
- `list_query_snippets` — List query snippets
- `get_query_snippet` — Get snippet details
- `create_query_snippet` — Create a query snippet
- `update_query_snippet` — Update a query snippet
- `delete_query_snippet` — Delete a query snippet

### Destinations (1)
- `list_destinations` — List notification destinations

## Resources

- `redash://data_sources` — List of all data sources
- `redash://queries` — List of recent queries
- `redash://dashboards` — List of dashboards
- `redash://datasource/{id}/schema` — Data source schema
- `redash://query/{id}` — Query details
- `redash://dashboard/{slug}` — Dashboard details

## Prompts

- `explore_data` — Explore data from a data source
- `build_dashboard` — Build a new dashboard
- `setup_alert` — Set up an alert for a query
- `optimize_query` — Optimize a SQL query
- `monitor_system` — Monitor Redash system health

## Development

### Setup

```bash
git clone https://github.com/yourusername/redash-mcp-server.git
cd redash-mcp-server
npm install
```

### Build

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

### Local Testing

```bash
REDASH_API_KEY=your-key REDASH_API_URL=http://localhost:5000/api npm start
```

## Publishing to npm

1. Update `package.json` with your package name (e.g., `@yourusername/redash-mcp-server`)
2. Build the project: `npm run build`
3. Login to npm: `npm login`
4. Publish: `npm publish --access public`

## License

MIT License — see [LICENSE](LICENSE) file for details.