Redash Connector MCP

redash连接器mcp

](https://www.npmjs.com/package/redash-connector-mcp)   

一种模型上下文协议（MCP）服务器，可实现以下各项之间的无缝集成 红灰 Claude AI（桌面与代码）。通过与Claude的自然语言对话，直接查询数据仓库、管理查询和执行分析工作流。

日语版在这里

目录

• 特性
• 安装

- 快速入门（Claude MCP Add） - 手动安装

• 配置

- 环境变量 - 获取Redash API密钥

• 用法

- 对话示例

• 可用工具
• MCP资源
• 发展

- 先决条件 - 设置 - 测试 - 代码质量

• 故障排除
• 安全
• 贡献
• 许可证

特性

🔍 综合查询管理

• 列表和搜索：使用分页浏览查询、按标签筛选、按关键字搜索
• CRUD操作：创建、读取、更新和存档查询
• 采用智能标签：使用标签组织查询并检索标签统计信息

⚡ 查询执行

• 异步轮询：使用自动作业轮询执行长时间运行的查询
• 参数化查询：将动态参数传递给查询
• 缓存结果：无需重新执行即可检索缓存结果（可配置TTL）

📊 仪表板和数据源管理

• 仪表板访问：列出并查看Redash仪表板
• 数据源发现：探索可用数据源

🔗 MCP资源

• 资源URI：将查询和仪表板作为MCP资源访问(redash://query/{id}, redash://dashboard/{id})
• 元数据：在一次调用中获取查询定义和执行结果

🛡️ 生产就绪

• 类型安全：具有严格类型检查的完整TypeScript实现
• 错误处理：全面的错误处理和详细的日志记录
• 测试覆盖率：107个单元测试的测试覆盖率超过86%
• 日志记录：可配置的日志记录级别（调试、信息、警告、错误）

安装

快速入门（Claude MCP Add）

最简单的安装方法是使用 claude mcp add 命令：

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

替换以下内容：

• https://your-redash-instance.com -您的Redash实例URL
• your_api_key_here -您的Redash API密钥（请参阅 获取Redash API密钥)

此命令将：

1. 通过npx自动安装最新版本（无需全局安装）
2. 使用您的凭据配置MCP服务器
3. 使其在Claude桌面/代码中可用

运行此命令后，重新启动Claude Desktop/Code以激活服务器。

手动安装

1.安装软件包

npm install -g redash-connector-mcp

2.配置MCP设置

将以下内容添加到您的Claude MCP配置文件中：

macOS/Linux: ~/.claude/config.json 视窗: %APPDATA%\Claude\config.json

{
  "mcpServers": {
    "redash": {
      "command": "redash-connector-mcp",
      "env": {
        "REDASH_URL": "https://your-redash-instance.com",
        "REDASH_API_KEY": "your_api_key_here"
      }
    }
  }
}

3.重启克劳德

重新启动Claude Desktop或Claude Code以加载MCP服务器。

配置

环境变量

MCP服务器需要以下环境变量：

环境变量可以通过三种方式提供：

1. .env 文件（建议用于团队项目）

创建一个 .env 项目根目录中的文件（其中 .mcp.json 位于）：

REDASH_URL=https://your-redash-instance.com
REDASH_API_KEY=your_api_key_here
REDASH_TIMEOUT=30000
LOG_LEVEL=INFO

然后参考它们 ${VAR} 语法在 .mcp.json:

{
  "mcpServers": {
    "redash": {
      "command": "npx",
      "args": ["redash-connector-mcp"],
      "env": {
        "REDASH_URL": "${REDASH_URL}",
        "REDASH_API_KEY": "${REDASH_API_KEY}"
      }
    }
  }
}

这种方法可以保密 .mcp.json，允许它安全地提交给git，同时 .env 留在 .gitignoreCLI入口点使用 dotenv 随着 override: true，所以 .env 值始终优先。

2. claude mcp add 命令

环境变量直接通过以下方式传递 --env 标志（否 .env 需要文件）。

3.MCP配置中的直接值

直接在 env MCP配置的字段（不建议用于共享存储库）。

获取Redash API密钥

1. 登录到您的Redash实例
2. 点击您的个人资料图标（右上角）
3. 导航至 设置 → 账户
4. 查找或生成您的 API密钥 在“API密钥”部分下
5. 复制密钥并将其用作 REDASH_API_KEY

安全说明：对API密钥保密。永远不要将其提交给版本控制。

用法

配置后，通过与Claude的自然语言对话与Redash进行交互：

对话示例

查询管理

You: "List all queries tagged with 'sales'"
Claude: [Uses list-queries tool with tag filter]

You: "Show me query ID 123"
Claude: [Uses get-query tool]

You: "Create a query named 'Daily Revenue' that selects from the sales table"
Claude: [Uses create-query tool]

You: "Update query 123 to include WHERE date > '2024-01-01'"
Claude: [Uses update-query tool]

查询执行

You: "Execute query 430"
Claude: [Uses execute-query tool, polls async job if needed]

You: "Run query 430 with start_date='2024-01-01' and end_date='2024-12-31'"
Claude: [Uses execute-query tool with parameters]

You: "Get the cached results for query 430"
Claude: [Uses get-query-results tool]

仪表板和数据源

You: "Show me all dashboards"
Claude: [Uses list-dashboards tool]

You: "What data sources are available?"
Claude: [Uses list-data-sources tool]

You: "Show me the details of dashboard 5"
Claude: [Uses get-dashboard tool]

分析与洞察

You: "What are the most commonly used query tags?"
Claude: [Uses list-query-tags tool]

You: "Find all queries about customer churn"
Claude: [Uses list-queries with search parameter]

可用工具

MCP服务器提供11个与Redash交互的工具：

查询管理（5个工具）

查询执行（2个工具）

仪表板管理（2个工具）

数据源管理（1个工具）

标签管理（1个工具）

MCP资源

服务器将Redash查询和仪表板作为MCP资源公开，使Claude能够发现和读取它们：

资源URI

• 查询: redash://query/{queryId}
• 仪表盘: redash://dashboard/{dashboardId}

资源发现

Claude可以通过以下方式自动发现可用的查询和仪表板 listResources() MCP终点。

阅读资源

在读取查询资源时，响应包括：

• 查询定义（名称、SQL、描述、标签等）
• 最新执行结果（如有）
• 元数据（创建日期、作者等）

示例资源读取：

{
  "uri": "redash://query/123",
  "mimeType": "application/json",
  "contents": {
    "query": { "id": 123, "name": "Sales Report", "query": "SELECT ..." },
    "result": { "data": { "rows": [...], "columns": [...] } }
  }
}

发展

先决条件

• Node.js 18+（推荐：Node.js 20 LTS）
• npm 9+
• Redash实例（用于测试）

设置

1. 克隆存储库

   git clone https://github.com/yourusername/redash-connector-mcp.git
   cd redash-connector-mcp

1. 安装依赖项

   npm install

1. 设置环境变量

   cp .env.example .env
   # Edit .env with your Redash credentials

1. 构建项目

   npm run build

测试

该项目使用 Vitest 对于覆盖率超过86%的测试：

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

测试结构:

• tests/unit/ -核心模块的单元测试
• tests/helpers/ -测试助手和模拟
• tests/fixtures/ -测试数据夹具

覆盖范围报告:

File             | Lines  | Funcs  | Branch | Stmts
-----------------|--------|--------|--------|--------
All files        | 86.33% | 93.33% | 73.42% | 83.94%
 index.ts        | 75%    | 83.33% | 55.38% | 73.41%
 logger.ts       | 100%   | 100%   | 100%   | 100%
 redashClient.ts | 99.11% | 100%   | 88.15% | 95.16%

代码质量

# Type checking
npm run typecheck

# Linting
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code
npm run format

预提交钩子：Husky+lint stage自动对stage文件运行linting和格式化。

与克劳德共同发展

要使用Claude Desktop/Code测试您的本地版本，请执行以下操作：

{
  "mcpServers": {
    "redash-dev": {
      "command": "node",
      "args": ["/absolute/path/to/redash-connector-mcp/dist/index.js"],
      "env": {
        "REDASH_URL": "https://your-redash-instance.com",
        "REDASH_API_KEY": "your_api_key_here",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

故障排除

常见问题

错误：“缺少所需的环境变量：REDASH_URL、REDASH_API_KEY”

原因：环境变量配置不正确。

解决方案:

1. 如果使用 .env 文件：确保 .env 文件存在于您的项目根目录中（与 .mcp.json)并包含 REDASH_URL 和 REDASH_API_KEY
2. 如果使用MCP配置：确保 REDASH_URL 和 REDASH_API_KEY 设置在 env 部分
3. 更改后重新启动Claude
4. 检查MCP服务器日志以了解详细的错误消息

错误：“查询执行超时”

原因：查询所用的时间超过了配置的超时时间。

解决方案:

1. 增加 REDASH_JOB_TIMEOUT （默认值：60000ms）

   "env": {
     "REDASH_URL": "...",
     "REDASH_API_KEY": "...",
     "REDASH_JOB_TIMEOUT": "120000"
   }

1. 优化Redash web界面中的查询
2. 直接在Redash中检查查询是否成功执行

错误：“无法从Redash获取查询”

原因：连接或身份验证问题。

解决方案:

1. 验证 REDASH_URL 正确且可从您的机器访问
2. 在浏览器中测试URL： https://your-redash-instance.com/api/queries
3. 验证 REDASH_API_KEY 有效（必要时重新生成）
4. 检查网络连接和防火墙设置
5. 确保您的Redash实例正在运行

MCP服务器未出现在Claude中

解决方案:

1. 完全重新启动Claude Desktop/代码（退出并重新打开）
2. 检查MCP配置文件语法（必须是有效的JSON）
3. 验证 command 路径正确
4. 检查Claude的MCP日志中的错误消息

调试

启用调试日志记录以获取详细信息：

{
  "mcpServers": {
    "redash": {
      "command": "redash-connector-mcp",
      "env": {
        "REDASH_URL": "https://your-redash-instance.com",
        "REDASH_API_KEY": "your_api_key_here",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

日志将出现在Claude的MCP服务器日志面板中。

安全

最佳实践

1. API密钥安全

- 永远不要将API密钥提交到版本控制 - 使用环境变量或安全密钥管理 - 定期旋转API密钥 - 尽可能使用只读API密钥

1. 网络安全

- 对Redash实例URL使用HTTPS - 如果您的Redash实例支持IP白名单，请考虑将其列入白名单 - 对敏感数据使用VPN或专用网络

1. 访问控制

- MCP服务器继承Redash API密钥的权限 - 使用具有最低必要权限的API密钥 - 避免使用管理员API密钥进行日常操作

报告安全问题

如果您发现安全漏洞，请发送电子邮件至 security@example.com 而不是使用问题跟踪器。

贡献

我们欢迎捐款！以下是您可以提供帮助的方式：

入门指南

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 进行更改
4. 编写或更新测试
5. 确保所有测试通过(npm test)
6. 确保代码质量检查通过(npm run lint && npm run typecheck)
7. 提交您的更改(git commit -m 'Add amazing feature')
8. 推到分支(git push origin feature/amazing-feature)
9. 打开拉取请求

开发指南

• 代码风格：遵循现有的代码风格（由ESLint+Prettier强制执行）
• 测试：保持或提高测试覆盖率（目前为86%以上）
• 文档：更新README.md以获取新功能
• 承诺：使用清晰、描述性的提交消息
• 类型：为所有新代码添加正确的TypeScript类型

拉取请求流程

1. 用更改的详细信息更新README.md（如果适用）
2. 添加新功能的测试
3. 确保测试套件通过
4. 更新以下版本号 学期
5. 一旦维护人员批准，PR将被合并

行为准则

该项目遵循 贡献者契约行为准则.

路线图

正在考虑的未来增强功能：

• \[\]具有可配置TTL的查询结果缓存
• \[\]批量查询执行
• \[\]查询调度管理
• \[\]警报配置
• \[\]可视化元数据提取
• \[\]查询性能指标
• \[\]多实例支持
• \[\]查询完成的Webhook支持

看 问题 用于主动功能请求。

相关项目

• 模型上下文协议 -MCP规范
• 红灰 -开源数据可视化平台
• 克劳德桌面版 -Claude AI的桌面应用程序
• 克劳德代码 -Claude AI的VS代码扩展

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

致谢

• 与 模型上下文协议SDK
• 由...驱动 Redash API
• TypeScript、Vitest和令人惊叹的开源社区

______________________________________________________________________

由以下材料制成❤️ Redash和Claude AI社区

如果你觉得这个项目有用，请考虑给它一个⭐ 在GitHub上！