内容
# redash-mcp
[](https://www.npmjs.com/package/redash-mcp)
[](https://www.npmjs.com/package/redash-mcp)
[](https://nodejs.org)
[](https://smithery.ai/servers/dev-seob717/redash-mcp)
[](https://glama.ai/mcp/servers/seob717/redash-mcp)
简体中文 | [한국어](README.ko.md) | [日本語](README.ja.md)
> 连接 [Redash](https://redash.io) 至 Claude AI 的 MCP 服务器 — 查询数据、管理仪表盘、自然语言运行 SQL。
[为什么选择 redash-mcp](#为什么选择redash-mcp) · [功能](#功能) · [安装](#安装) · [环境变量](#环境变量) · [使用示例](#使用示例) · [隐私政策](#隐私政策)
---
## 为什么选择 redash-mcp？
有多个 Redash MCP 服务器。这个服务器是为让 LLM 安全地触及**生产**数据而构建的：
- **🛡️ SQL 安全防护** — 阻止 `DROP`/`TRUNCATE`/`ALTER` 和 `DELETE`/`UPDATE`（无 `WHERE` 条件）；`strict`/`warn`/`off` 模式，PII 检测和自动 `LIMIT`。将您的真实 Redash 交给 Claude，无需担心。
- **🧠 BIRD 智能查询** — 分析问题，自动选择正确的表格，并指导 SQL 生成（基于 [BIRD 文本转 SQL](https://bird-bench.github.io/) 方法论）。可选的 Claude Haiku 表格选择备用方案。
- **⚡ 一键安装** — `npx redash-mcp setup` 为您配置 Claude Desktop / Claude Code。无需手动编辑 JSON。
- **🔒 完全本地** — 直接与您的 Redash 实例通信。API 密钥和查询结果从未离开您的机器。
- **📊 端到端** — 查询、保存、复制、仪表盘、部件和警报 — 6 类 20+ 工具。
---
## 功能
### 工具
| 类别 | 工具 | 描述 |
|---|---|---|
| 数据源 | `list_data_sources` | 列出连接的数据源 |
| 架构 | `list_tables` | 列出表格（支持关键字搜索） |
| 架构 | `get_table_columns` | 获取列名和类型 |
| 智能查询 | `smart_query` | 分析问题，自动选择表格，指导 SQL 生成（BIRD） |
| 智能查询 | `get_bird_config` | 检查活动的 BIRD 智能查询配置 |
| 智能查询 | `evaluate_queries` | 评估生成的 SQL 与预期结果 |
| 智能查询 | `submit_query_feedback` | 记录反馈以改进未来的表格选择 |
| 智能查询 | `manage_few_shot_examples` | 添加/列出 BIRD 少量示例 |
| 智能查询 | `manage_keyword_map` | 添加/列出关键字→表格映射 |
| 查询 | `run_query` | 执行 SQL 并返回结果 |
| 已保存的查询 | `list_queries` | 列出已保存的查询 |
| 已保存的查询 | `get_query` | 获取查询详情（SQL，视觉化） |
| 已保存的查询 | `get_query_result` | 运行已保存的查询并获取结果 |
| 已保存的查询 | `create_query` | 保存新的查询 |
| 已保存的查询 | `update_query` | 更新已保存的查询 |
| 已保存的查询 | `fork_query` | 复制已保存的查询 |
| 已保存的查询 | `archive_query` | 存档（删除）查询 |
| 仪表盘 | `list_dashboards` | 列出仪表盘 |
| 仪表盘 | `get_dashboard` | 获取仪表盘详情和部件 |
| 仪表盘 | `create_dashboard` | 创建新的仪表盘 |
| 仪表盘 | `add_widget` | 向仪表盘添加视觉化部件 |
| 警报 | `list_alerts` | 列出警报 |
| 警报 | `get_alert` | 获取警报详情 |
| 警报 | `create_alert` | 创建新的警报 |
### SQL 安全防护
保护您的数据库免受危险查询：
- **始终阻止**：`DROP`，`TRUNCATE`，`ALTER TABLE`，`GRANT/REVOKE`，无 `WHERE` 的 `DELETE/UPDATE`
- **警告（warn 模式）/ 阻止（strict 模式）**：`SELECT *`，无 `WHERE` 或 `LIMIT` 的查询，PII 列访问
- **自动 LIMIT**：当设置了 `REDASH_AUTO_LIMIT` 时，自动追加 `LIMIT N`
### 查询缓存
结果在内存中缓存以减少冗余 API 调用：
- TTL：通过 `REDASH_MCP_CACHE_TTL` 配置（默认：300s）
- 最大内存：通过 `REDASH_MCP_CACHE_MAX_MB` 配置（默认：50MB）
---
## 安装
### 自动安装（推荐）
```bash
npx redash-mcp setup
```
安装向导将指导您配置 Claude Desktop，Claude Code（CLI）或两者。
### Shell 脚本安装
一键安装 Node.js，Claude Desktop 和 MCP 配置：
```bash
curl -fsSL https://raw.githubusercontent.com/seob717/redash-mcp/main/install.sh | bash
```
### 手动安装
#### 1. 获取您的 Redash API 密钥
前往 Redash → 个人资料（右上角）→ **编辑个人资料** → 复制 **API 密钥**
#### 2-A. Claude Desktop
打开 `~/Library/Application Support/Claude/claude_desktop_config.json` 并添加：
```json
{
"mcpServers": {
"redash-mcp": {
"command": "npx",
"args": ["-y", "redash-mcp"],
"env": {
"REDASH_URL": "https://your-redash-instance.com",
"REDASH_API_KEY": "your_api_key_here"
}
}
}
}
```
保存后完全退出并重启 Claude Desktop。
#### 2-B. Claude Code（CLI）
打开 `~/.claude/settings.json` 并添加：
```json
{
"mcpServers": {
"redash-mcp": {
"command": "npx",
"args": ["-y", "redash-mcp"],
"env": {
"REDASH_URL": "https://your-redash-instance.com",
"REDASH_API_KEY": "your_api_key_here"
}
}
}
}
```
> **macOS**：如果找不到 `npx`，请运行 `which npx` 获取完整路径并使用。
---
## 环境变量
### 必需
| 变量 | 描述 |
|---|---|
| `REDASH_URL` | Redash 实例 URL（例如 `https://redash.example.com`） |
| `REDASH_API_KEY` | Redash 用户 API 密钥 |
### 可选
| 变量 | 默认值 | 描述 |
|---|---|---|
| `REDASH_SAFETY_MODE` | `warn` | SQL 安全级别：`off` / `warn` / `strict` |
| `REDASH_SAFETY_DISABLE_PII` | `false` | 禁用 PII 检测 |
| `REDASH_SAFETY_DISABLE_COST` | `false` | 禁用成本警告 |
| `REDASH_AUTO_LIMIT` | `0` | 自动为无 `LIMIT` 查询追加 `LIMIT N`（0 = 禁用） |
| `REDASH_DEFAULT_MAX_AGE` | `0` | Redash 缓存 TTL（秒） |
| `REDASH_MCP_CACHE_TTL` | `300` | MCP 查询缓存 TTL（秒）（0 = 禁用） |
| `REDASH_MCP_CACHE_MAX_MB` | `50` | MCP 查询缓存最大内存（MB） |
| `REDASH_MCP_CONFIG_DIR` | `~/.redash-mcp` | BIRD 少量示例、反馈、评估、关键字映射数据目录 |
| `REDASH_BIRD_ENABLED` | `true` | 设置为 `false` 以禁用 BIRD 智能查询工具 |
| `REDASH_HTTP_TIMEOUT_SECS` | `30` | Redash API 请求超时（秒） |
| `ANTHROPIC_API_KEY` | — | 如果设置，BIRD 智能查询在关键字评分失败时降级为 Claude Haiku 表格选择 |
---
## 使用示例
只需用自然语言询问 Claude：
- "显示用户表格中的列"
- "运行查询以获取过去 7 天的订单数量"
- "列出所有已保存的查询"
- "显示收入仪表盘中的部件"
- "当每日注册人数低于 100 时创建警报"
### 示例 1：用自然语言查询数据
> **提示**："这个月有多少新用户注册？"
**工具流程：**
1. `list_data_sources` → 确定目标数据源
2. `smart_query` → 分析问题，自动选择 `User` 表，提供 SQL 生成指导
3. `run_query` → 执行生成的 SQL
**结果：**
```
这个月有 18,197 个新注册用户。
```
### 示例 2：复杂的业务问题
> **提示**："上周新注册用户中有多少比例进行了购买？"
**工具流程：**
1. `smart_query` → 分析问题，自动选择 `User` 和 `Payment` 表，提供 JOIN 查询指导
2. `run_query` → 执行 SQL
**结果：**
```
上周 1,204 名新注册用户中，312 人进行了购买（25.9%）。
```
### 示例 3：创建查询和仪表盘
> **提示**："创建一个每月收入趋势查询并添加到仪表盘"
**工具流程：**
1. `smart_query` → 分析收入相关表格
2. `create_query` → 保存 "每月收入趋势" 查询
3. `create_dashboard` → 创建 "收入仪表盘"
4. `get_query` → 从已保存的查询中获取视觉化 ID
5. `add_widget` → 将图表部件添加到仪表盘
**结果：**
```
创建了包含每月收入趋势图表的 "收入仪表盘"。
在 Redash 中查看：https://your-redash.com/dashboard/monthly-revenue
```
---
## 隐私政策
### 数据收集和处理
redash-mcp 是一个 **本地 MCP 服务器**，直接与您的 Redash 实例通信。无需中间服务器。
| 项目 | 描述 |
|------|-------------|
| **Redash API 密钥** | 仅存储为本地环境变量（`REDASH_API_KEY`）。从未外部传输。 |
| **查询内容和结果** | 仅通过 MCP 协议传递给本地 MCP 客户端（Claude Desktop/Code）。 |
| **BIRD SQL 设置** | 仅存储在本地文件中（`~/.redash-mcp/`）。包括少量示例、关键字映射和反馈。 |
| **LLM 降级** | 当设置了 `ANTHROPIC_API_KEY` 时，仅将表格名称列表发送到 Anthropic API。从未传输查询数据和结果。 |
### 第三方共享
我们不会出售或与第三方共享用户数据。当启用 LLM 降级功能时，仅将表格名称列表发送到 Anthropic API，并且仅当用户明确配置了 `ANTHROPIC_API_KEY`。
### 数据保留
- **配置文件**：存储在本地 `~/.redash-mcp/`（用户可以随时删除）
- **查询缓存**：仅内存，服务器关闭后清除
- **架构缓存**：仅内存，10 分钟 TTL 后自动过期
### 联系方式
询问和安全报告：[GitHub 问题](https://github.com/seob717/redash-mcp/issues)
---
## 免责声明
redash-mcp 是一个非官方的、社区构建的集成，**不隶属于、获得 Redash 的认可或赞助**。"Redash" 是其各自所有者的商标，仅在此用于描述兼容性。该项目仅通过其公共 REST API 与 Redash 通信。
## 许可证
MIT © seob717
