使用说明

项目简介

本项目是一个基于 Model Context Protocol (MCP) 协议实现的服务器端应用，它利用 Apache Superset 的 REST API，将 Superset 的数据查询能力以 MCP 工具的形式提供给大型语言模型 (LLM)。通过此服务器，LLM 可以安全、可控地访问和查询 Superset 中的数据，从而扩展 LLM 在数据分析和处理方面的能力。

主要功能点

数据库查询：允许 LLM 通过自然语言查询 Superset 中配置的数据库。
表信息查询：支持 LLM 获取数据库中的表列表以及表的详细信息。
字段信息查询：允许 LLM 获取指定表的字段列表及其数据类型等信息。
SQL 执行：支持 LLM 执行 SQL 查询语句，并获取查询结果。

安装步骤

安装 Node.js 环境：确保您的环境中已安装 Node.js (>= 14.0.0)。
安装依赖：克隆或下载仓库代码后，在项目根目录下运行以下命令安装项目依赖：
```
npm install
```

配置环境变量：复制仓库中的 '.env.example' 文件并重命名为 '.env'，根据您的 Superset 实例配置以下环境变量：

SUPERSET_URL=您的Superset服务器地址 (例如: http://localhost:8088)
SUPERSET_USERNAME=您的Superset用户名
SUPERSET_PASSWORD=您的Superset密码

请务必正确配置 Superset 的连接信息，否则 MCP 服务器将无法正常工作。

服务器配置

MCP 客户端需要配置以下 JSON 格式的服务器信息以连接到 Superset 查询 MCP 服务器：

{
  "serverName": "superset-query",  // 服务器名称，与 MCP 服务器定义一致
  "command": "node",             // 启动服务器的命令，这里使用 node
  "args": [                       // 启动命令的参数
    "build/index.js"           //  指向编译后的服务器入口文件
  ]
}

配置参数说明:

'serverName': 服务器名称，必须与 'build/index.js' 中 'McpServer' 实例化的 'name' 属性值 ('superset-query') 一致。
'command': 启动 MCP 服务器的命令，由于本项目是 Node.js 应用，因此使用 'node' 命令。
'args': 命令参数，指向编译后的 'build/index.js' 文件，这是服务器的入口文件。

请注意:

确保 MCP 客户端能够访问到 'build/index.js' 文件，这通常意味着 MCP 客户端需要和 MCP 服务器部署在同一文件系统中，或者您需要根据实际部署情况调整 'args' 中的路径。
启动服务器前，请先执行 'npm run build' 命令编译 TypeScript 代码生成 'build/index.js' 文件。

基本使用方法

编译项目：在项目根目录下运行以下命令编译 TypeScript 代码：
```
npm run build
```
启动 MCP 服务器：编译成功后，可以通过以下命令启动 MCP 服务器：
```
npm start
```
或者直接使用 'node build/index.js' 命令启动。
MCP 客户端连接：配置您的 MCP 客户端，使用上述提供的服务器配置信息连接到 Superset 查询 MCP 服务器。
使用工具：成功连接后，MCP 客户端可以调用以下工具与 Superset 进行数据交互：
- 'query-superset': 执行 Superset 数据查询。
  - 参数：
    - 'query': 自然语言查询语句 (例如: "查询最近10条订单")
    - 'databaseId' (可选): 数据库 ID
    - 'schema' (可选): Schema 名称
    - 'tableName' (可选): 表名
- 'list-databases': 获取所有可用的数据库列表。
  - 无参数。
- 'list-tables': 获取指定数据库的表列表。
  - 参数：
    - 'databaseId': 数据库 ID
    - 'schema' (可选): Schema 名称
- 'list-fields': 获取指定表的字段列表。
  - 参数：
    - 'databaseId': 数据库 ID
    - 'schema': Schema 名称
    - 'tableName': 表名
LLM 客户端可以通过调用这些工具，结合自然语言指令，实现对 Superset 数据的查询和分析。

快速开始 (直接使用 npx)

如果您只是想快速体验，可以使用 'npx' 命令直接运行服务器，无需安装和编译：

npx -y https://github.com/LiusCraft/superset-mcp-server

运行此命令后，请按照提示设置环境变量 'SUPERSET_URL', 'SUPERSET_USERNAME', 'SUPERSET_PASSWORD'，然后服务器将启动。

注意： 'npx' 方式适用于快速体验，生产环境建议使用安装和编译方式部署。

关键词