MCP For Redash

红灰MCP

将Codex、Claude Code、Cursor和其他MCP兼容的AI工具连接到Redash。

这个项目是一个用Python编写的本地MCP服务器。它为您的人工智能助手提供了一种结构化的方式来列出Redash资产、运行批准的只读查询、检查仪表板、管理警报，以及通过Redash API使用其他Redash对象。

安全第一

此存储库不需要您的Redash URL或API密钥就可以提交到GitHub。

• 此回购中不包含真正的API密钥
• 此仓库中没有硬编码私有Redash URL
• .env.example 仅包含占位符
• 您可以在本地计算机上添加自己的Redash连接详细信息

您可以通过以下任一方式提供凭据：

• 环境变量，如 REDASH_URL 和 REDASH_API_KEY
• 一个未提交到GitHub的本地JSON配置文件，包括多个命名的Redash实例

用通俗易懂的英语

如果你不懂技术，可以把它看作是你的人工智能助手和Redash之间的桥梁。

如果没有此MCP：

• 你的人工智能只能根据你输入的内容进行猜测
• 它不能直接查找Redash查询、仪表板或警报

使用此MCP：

• 你的人工智能可以查找真实的Redash数据和元数据
• 你可以用正常语言提问，而不是点击Redash屏幕
• 你可以说：

- “显示我最喜欢的Redash查询” - “在过去7天内运行查询133822” - “列出所有仪表板标签” - “显示哪些Redash实例可用”

简而言之：这会让你的AI助手表现得更像Redash的高级用户。

MCP是什么意思

MCP代表模型上下文协议。

这是AI客户端与外部工具对话的标准方式。

在本项目中：

1. 您的AI客户端在您的计算机上启动此服务器。
2. 服务器宣布它支持哪些工具。
3. 你的AI会在需要时调用这些工具。
4. 服务器与Redash对话并返回结构化结果。

你能做什么

此服务器当前支持：

• 数据源：列出Redash数据源
• 查询：列表、搜索、检查、创建、更新、存档、收藏、分叉、执行
• 仪表板：列表、检查、创建、更新、存档、收藏、分叉
• 警报：列出、检查、创建、更新、删除、静音、管理订阅
• 可视化：检查、创建、更新、删除
• 小部件：列表、检查、创建、更新、删除
• 目的地：列出警报目的地

默认情况下，服务器以强化企业模式启动：

• read_only 默认情况下已启用
• 默认情况下禁用即席SQL
• 查询执行仅限于只读SQL
• Redash API错误体未逐字回显

先决条件

您需要：

• Python 3.10或更新版本
• 访问Redash实例
• Redash API密钥
• MCP兼容客户端，如Codex、Claude Code、Cursor或其他可以运行本地stdio MCP服务器的工具

快速开始

1.克隆仓库

git clone https://github.com/Ashuqwe/mcp-for-redash.git
cd mcp-for-redash

2.创建虚拟环境

python3 -m venv .venv
source .venv/bin/activate

3.安装服务器

python3 -m pip install -e .

4.准备您的Redash设置

你有两个安全的选择。

选项A：使用环境变量

export REDASH_URL="https://your-redash.example.com"
export REDASH_API_KEY="YOUR_REDASH_API_KEY"

可选：

export REDASH_TIMEOUT_SECONDS="300"
export REDASH_MCP_MAX_ROWS="200"
export REDASH_MCP_READ_ONLY="true"
export REDASH_MCP_ALLOW_ADHOC_SQL="false"
export REDASH_MCP_DEFAULT_INSTANCE="default"

您可以复制 .env.example 作为参考，但不要承诺你的真实 .env 文件。

选项B：使用本地JSON配置文件

复制 config.example.json 到版本控制之外的本地文件，例如：

mkdir -p ~/.config/redash-mcp
cp config.example.json ~/.config/redash-mcp/config.json

然后用你自己的值编辑它：

{
  "default_instance": "prod",
  "read_only": true,
  "allow_adhoc_sql": false,
  "instances": {
    "prod": {
      "base_url": "https://your-redash.example.com",
      "api_key": "YOUR_REDASH_API_KEY"
    },
    "staging": {
      "base_url": "https://your-staging-redash.example.com",
      "api_key": "YOUR_STAGING_REDASH_API_KEY"
    }
  }
}

如果你想将该文件存储在其他地方，请设置：

export REDASH_MCP_CONFIG="/absolute/path/to/your/config.json"

如何将其连接到Codex

这些命令已根据此计算机上的本地Codex CLI帮助进行了验证。

选项1：使用Codex CLI添加它

在虚拟环境中使用Python解释器，这样Codex总是可以找到包：

codex mcp add redash \
  --env REDASH_URL=https://your-redash.example.com \
  --env REDASH_API_KEY=YOUR_REDASH_API_KEY \
  --env REDASH_TIMEOUT_SECONDS=300 \
  --env REDASH_MCP_MAX_ROWS=200 \
  --env REDASH_MCP_READ_ONLY=true \
  --env REDASH_MCP_ALLOW_ADHOC_SQL=false \
  -- /ABSOLUTE/PATH/TO/mcp-for-redash/.venv/bin/python -m redash_mcp_server

检查是否已注册：

codex mcp list
codex mcp get redash

选项2：添加 ~/.codex/config.toml

[mcp_servers.redash]
command = "/ABSOLUTE/PATH/TO/mcp-for-redash/.venv/bin/python"
args = ["-m", "redash_mcp_server"]

[mcp_servers.redash.env]
REDASH_URL = "https://your-redash.example.com"
REDASH_API_KEY = "YOUR_REDASH_API_KEY"
REDASH_TIMEOUT_SECONDS = "300"
REDASH_MCP_MAX_ROWS = "200"
REDASH_MCP_READ_ONLY = "true"
REDASH_MCP_ALLOW_ADHOC_SQL = "false"

如何将其连接到Claude代码

这些说明遵循Anthropic针对本地stdio服务器的官方Claude Code MCP文档。

选项1：使用Claude CLI添加它

claude mcp add --transport stdio \
  --env REDASH_URL=https://your-redash.example.com \
  --env REDASH_API_KEY=YOUR_REDASH_API_KEY \
  --env REDASH_TIMEOUT_SECONDS=300 \
  --env REDASH_MCP_MAX_ROWS=200 \
  --env REDASH_MCP_READ_ONLY=true \
  --env REDASH_MCP_ALLOW_ADHOC_SQL=false \
  redash \
  -- /ABSOLUTE/PATH/TO/mcp-for-redash/.venv/bin/python -m redash_mcp_server

检查一下：

claude mcp list
claude mcp get redash

在Claude Code中，您还可以使用：

/mcp

选项2：将其添加为项目范围 .mcp.json

{
  "mcpServers": {
    "redash": {
      "command": "/ABSOLUTE/PATH/TO/mcp-for-redash/.venv/bin/python",
      "args": ["-m", "redash_mcp_server"],
      "env": {
        "REDASH_URL": "https://your-redash.example.com",
        "REDASH_API_KEY": "YOUR_REDASH_API_KEY",
        "REDASH_TIMEOUT_SECONDS": "300",
        "REDASH_MCP_MAX_ROWS": "200",
        "REDASH_MCP_READ_ONLY": "true",
        "REDASH_MCP_ALLOW_ADHOC_SQL": "false"
      }
    }
  }
}

如何将其连接到游标或其他MCP客户端

许多MCP客户端接受带有命令、args和env块的JSON配置。

例子：

{
  "mcpServers": {
    "redash": {
      "command": "/ABSOLUTE/PATH/TO/mcp-for-redash/.venv/bin/python",
      "args": ["-m", "redash_mcp_server"],
      "env": {
        "REDASH_URL": "https://your-redash.example.com",
        "REDASH_API_KEY": "YOUR_REDASH_API_KEY",
        "REDASH_TIMEOUT_SECONDS": "300",
        "REDASH_MCP_MAX_ROWS": "200",
        "REDASH_MCP_READ_ONLY": "true",
        "REDASH_MCP_ALLOW_ADHOC_SQL": "false"
      }
    }
  }
}

如果您的客户端仅支持HTTP MCP服务器，则此仓库不是现成的。此服务器使用 stdio.

连接后如何使用

此MCP被优化为首先进行总结。默认情况下，列表工具和大多数读取工具返回压缩元数据，只有当客户端明确要求时，详细对象才可用 full=true。查询结果行的上限为 REDASH_MCP_MAX_ROWS，默认为 200 以保持较低层计划中令牌使用的可预测性。

每个工具还接受一个可选 instance 当您配置多个Redash环境时。使用 list_redash_instances 首先，如果你想让人工智能从你配置的实例中进行选择。

默认安全态势为：

• REDASH_MCP_READ_ONLY=true
• REDASH_MCP_ALLOW_ADHOC_SQL=false
• 查询创建、查询更新、保存的查询执行和即席执行只接受只读SQL

安装MCP后，您通常不会手动调用工具。你只需询问你的AI助手你想要什么。

示例：

• “列出我最喜欢的Redash仪表板。”
• “显示我们最常用的查询标签。”
• “列出已配置的Redash实例。”
• “对过去14天的prod实例运行查询133822。”
• “运行过去14天的查询133822。”
• “找到名为收入概览的仪表板，并总结其中包含的内容。”
• 如果写入操作被禁用，请解释被阻止的内容及其原因

对非技术用户的良好提示

如果您不太了解Redash，请使用以下提示：

• “找到与航班取消相关的仪表板，并简单解释。”
• “显示我最常用的查询。”
• “运行上周的销售查询，并用简单的术语解释结果。”
• “显示我应该将哪个Redash实例用于生产报告。”
• “对于失败的预订，已经存在哪些警报？”
• “我们使用哪些仪表板标签进行营销？”

工具组

该MCP暴露出相当宽的工具表面。主要群体包括：

• 查询工具

- list_redash_instances - list_queries - list_my_queries - list_recent_queries - list_favorite_queries - get_query - create_query - update_query - archive_query - add_query_favorite - remove_query_favorite - fork_query - execute_saved_query - execute_adhoc_query

• 仪表板工具

- list_dashboards - list_my_dashboards - list_favorite_dashboards - get_dashboard - create_dashboard - update_dashboard - archive_dashboard - fork_dashboard - add_dashboard_favorite - remove_dashboard_favorite

• 警报工具

- list_alerts - get_alert - create_alert - update_alert - delete_alert - mute_alert - get_alert_subscriptions - add_alert_subscription - remove_alert_subscription

• 可视化和小部件工具

- get_visualization - create_visualization - update_visualization - delete_visualization - list_widgets - get_widget - create_widget - update_widget - delete_widget

• 元数据工具

- list_data_sources - get_query_tags - get_dashboard_tags - list_destinations

资源

此MCP还公开了一些资源：

• redash://instances
• redash://data-sources
• redash://query/{query_id}
• redash://dashboard/{slug}

当客户端希望通过URI而不是调用工具来获取只读上下文时，资源非常有用。

兼容性说明

• 此项目仅使用用户提供的本地配置。
• 它支持环境变量或本地JSON配置文件。
• 它通过JSON配置文件支持多个命名的Redash实例。
• 它默认为只读模式，并在显式启用之前阻止即席SQL。
• 它只允许只读SQL，这会阻止此MCP用于通过查询执行创建、更新、删除、删除或截断表。
• 一些Redash部署与参考TypeScript项目使用的端点略有不同。
• 此服务器包括以下兼容性回退 list_my_dashboards 当 /api/dashboards/my 不见了。
• 在开发过程中使用的Redash部署上， /api/visualizations/{id} 返回的是HTML而不是JSON。在这种情况下，此服务器现在会引发一个明显的错误，而不是返回损坏的数据。
• 默认情况下，通过以下方式实现但禁用可变端点 REDASH_MCP_READ_ONLY=true.

故障排除

错误： redash-mcp-server: command not found

直接使用虚拟环境的Python：

/ABSOLUTE/PATH/TO/mcp-for-redash/.venv/bin/python -m redash_mcp_server

错误：Redash的身份验证或权限失败

检查：

• REDASH_URL
• REDASH_API_KEY
• REDASH_MCP_DEFAULT_INSTANCE
• 该API密钥是否具有读取或修改目标对象的权限

错误：AI表示MCP服务器不可用

检查：

• MCP配置中的命令路径
• 您的虚拟环境仍然存在
• 那 python3 -m pip install -e . 成功完成
• 您的AI客户端已启用服务器

错误：可视化详细信息请求失败

某些Redash部署不会将可视化细节作为JSON API路由公开。在这种情况下，MCP返回一条明确的错误消息，而不是格式错误的输出。

本地开发

安装以进行开发：

python3 -m pip install -e .

运行测试：

python3 -m unittest discover -s tests -v

学分

该项目遵循与 suthio/redash-mcp，但它是用Python实现的，并为本地stdio MCP使用量身定制。