AI导哈

Superset自然语言查询桥接器

连接Apache Superset与Claude桌面的MCP桥接工具，支持通过自然语言查询数据仪表盘和数据集。

  • by Sanjeevaraj-Ethirweerasingham
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Sanjeevaraj-Ethirweerasingham/superset-mcp-bridge

使用说明

超级设置MCP桥

将Apache Superset连接到Claude Desktop -用自然语言询问有关数据的问题！

这是什么？

此MCP（模型上下文协议）桥允许您将Claude Desktop连接到Apache Superset实例。用简单的英语问数据问题，并从仪表板和数据集中获得即时答案。

示例查询：

  • “显示所有可用的仪表板”
  • “按地区划分的第三季度销售额是多少？”
  • “列出财务数据库中的所有数据集”
  • “执行此SQL:SELECT*FROM用户限制10”

特性

✅ 安全 -所有查询都尊重Superset的RBAC和RLS
✅ 本地 -在您的机器上运行，连接到内部Superset
✅ 快速 -在几秒钟内得到答案，而不是几分钟
✅ 简单 -15分钟设置，分步说明

快速开始

先决条件

  • Apache Superset实例（可通过HTTP/HTTPS访问）
  • 已安装Claude Desktop(点击此处下载)
  • Python 3.10或更高版本
  • 基本的命令行知识

安装

1.安装uv（Python包管理器）：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2.克隆此存储库：

git clone https://github.com/Sanjeevaraj-Ethirweerasingham/superset-mcp-bridge.git
cd superset-mcp-bridge

3.创建虚拟环境并安装依赖关系：

uv venv
uv pip install -e .

4.配置环境变量：

# Copy the example environment file
cp .env.example .env

# Edit .env with your Superset credentials
# (Use your favorite text editor)

编辑 .env 包括：

SUPERSET_BASE_URL=https://your-superset-instance.com 超级用户名=您的用户名 超级密码=您的密码

5.配置克劳德桌面：

找到您的Claude Desktop配置文件：

  • 窗户： %APPDATA%\Claude\claude_desktop_config.json
  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux： ~/.config/Claude/claude_desktop_config.json

添加此配置（调整系统路径）：

对于Windows：

{
  "mcpServers": {
    "superset": {
      "command": "C:\\Users\\YOUR_USERNAME\\superset-mcp-bridge\\.venv\\Scripts\\python.exe",
      "args": ["-m", "main"],
      "env": {
        "SUPERSET_BASE_URL": "https://your-superset-instance.com",
        "SUPERSET_USERNAME": "your_username",
        "SUPERSET_PASSWORD": "your_password"
      }
    }
  }
}

对于macOS/Linux：

{
  "mcpServers": {
    "superset": {
      "command": "/Users/YOUR_USERNAME/superset-mcp-bridge/.venv/bin/python",
      "args": ["-m", "main"],
      "env": {
        "SUPERSET_BASE_URL": "https://your-superset-instance.com",
        "SUPERSET_USERNAME": "your_username",
        "SUPERSET_PASSWORD": "your_password"
      }
    }
  }
}

6.重新启动克劳德桌面

完全退出并重新启动Claude Desktop以使配置生效。

7.测试连接

在Claude Desktop中，查找🔌 插件图标。您应该在“超集”旁边看到一个绿色指示器。

试着问克劳德：

“列出Superset中的所有可用仪表板”

使用示例

连接后，您可以向Claude自然语言提问有关Superset数据的问题：

仪表盘

  • “显示我的所有仪表板”
  • “获取ID为5的仪表板的详细信息”
  • “创建一个名为“销售概述”的新仪表板”

图表

  • “列出Superset中的所有图表”
  • “显示ID为10的图表”
  • “从数据集3创建条形图”

数据集和数据库

  • “有哪些可用的数据集？”
  • “显示数据库1中的表”
  • “列出所有连接的数据库”

sql查询

  • “执行：从用户中选择*限制10”
  • 格式化此SQL:SELECT id，name FROM users WHERE active=1
  • “验证SQL:从订单中选择COUNT（*）”

可用工具

此桥为Claude提供了访问这些Superset操作的权限：

身份验证：

  • 检查令牌有效性
  • 刷新身份验证令牌

仪表板：

  • 列出、获取、创建、更新、删除仪表板

图表：

  • 列出、获取、创建、更新、删除图表

数据库：

  • 列出、获取、创建、更新、删除数据库连接
  • 获取表、模式、目录
  • 测试连接
  • 验证SQL

数据集：

  • 列出、获取、创建数据集

SQL实验室：

  • 执行查询
  • 设置SQL格式
  • 获取查询结果
  • 估算查询成本
  • 导出结果

用户和管理员：

  • 获取当前用户信息
  • 获取用户角色
  • 查看最近的活动
  • 管理标签

安全

🔒 这座桥的设计考虑到了安全性：

  • 无训练数据： 您的数据不用于训练AI模型
  • RBAC已强制执行： 所有Superset权限都得到充分尊重
  • 本地执行： 桥在你的机器上运行
  • 内部连接： 直接连接到您的内部Superset
  • 无数据存储： Bridge是无状态的，不存储任何数据
  • 凭证控制： 您在本地管理所有凭据

安全最佳实践：

  • 使用环境变量作为凭据（永远不要硬编码）
  • 使用具有最小权限的专用Superset服务帐户
  • 将凭据保存在 .env （已在 .gitignore)
  • 对于生产，考虑使用机密管理器
  • 定期轮换凭据

故障排除

“发现多个顶级模块”错误

将此添加到您的 pyproject.toml:

[tool.setuptools]
py-modules = ["main"]

身份验证失败

  1. 验证中的凭据 .env 文件
  2. 确保Superset可在指定的URL访问
  3. 检查用户名是否具有适当的权限
  4. 尝试使用相同的凭据手动登录Superset

Claude没有显示插件

  1. 确保您完全重新启动了Claude Desktop
  2. 检查路径 claude_desktop_config.json 是正确的
  3. 在Windows上，确保反斜杠加倍(\\)
  4. 验证Python路径指向虚拟环境的Python

“连接被拒绝”错误

  1. 验证Superset是否正在运行
  2. 检查防火墙设置
  3. 如果使用VPN，请确保您已连接
  4. 在浏览器中测试覆盖URL

权限被拒绝错误

Superset用户帐户需要适当的权限。在Superset的安全设置中验证。

有关更多故障排除，请参阅 docs/故障排除.md

系统要求

  • python 3.10或更高
  • 操作系统： Windows 10+、macOS 11+或Linux
  • 内存： 最低512MB RAM
  • 网络： 访问Superset实例
  • 克劳德桌面： 最新版本

架构流程

┌─────────────────┐
│  Claude Desktop │
│   (Local AI)    │
└────────┬────────┘
         │ MCP Protocol
         ▼
┌─────────────────┐
│   MCP Bridge    │
│    (Python)     │
│    - main.py    │
└────────┬────────┘
         │ Superset REST API (Authenticated)
         ▼
┌─────────────────┐
│    Superset     │
│    Instance     │
│  (Your Server)  │
└─────────────────┘


## Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
- Inspired by [aptro/superset-mcp](https://github.com/aptro/superset-mcp)
- Powered by [Apache Superset](https://superset.apache.org/)
- Uses [Anthropic's Claude](https://www.anthropic.com/claude)

## Support

- 📖 [Full Documentation](docs/)
- 🐛 [Report Issues](https://github.com/YOUR_USERNAME/superset-mcp-bridge/issues)
- 💬 [Discussions](https://github.com/YOUR_USERNAME/superset-mcp-bridge/discussions)

## Related Projects

- [aptro/superset-mcp](https://github.com/aptro/superset-mcp) - Original Superset MCP implementation
- [Model Context Protocol](https://github.com/modelcontextprotocol) - MCP specification
- [Claude Desktop](https://claude.ai/download) - AI assistant

---

**Made with ❤️ for the data community**

相关 MCP