# kes-mcp-server

**Repository Path**: king-db/kes-mcp-server

## Basic Information

- **Project Name**: kes-mcp-server
- **Description**: KingbaseES 数据库的 MCP Server，使 AI 助手具备数据库结构探索、SQL 执行、执行计划分析、索引优化和健康检查能力。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 7
- **Forks**: 3
- **Created**: 2026-05-27
- **Last Updated**: 2026-09-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KingbaseES MCP Server

KingbaseES 数据库的 MCP Server，使 AI 助手具备数据库结构探索、SQL 执行、执行计划分析、索引优化和健康检查能力。

[![MCP](https://img.shields.io/badge/MCP_SDK-1.25.x%E2%80%931.x-green)](https://modelcontextprotocol.io)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
[![KingbaseES](https://img.shields.io/badge/KingbaseES-V8R6%2B-orange)](https://www.kingbase.com.cn/)
[![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)

## 目录

- [架构说明](#架构说明)
- [产品特性](#产品特性)
- [功能说明](#功能说明)
- [前提条件](#前提条件)
- [安装部署](#安装部署)
- [配置说明](#配置说明)
- [使用说明](#使用说明)
- [安全说明](#安全说明)
- [项目结构](#项目结构)
- [许可证](#许可证)

## 架构说明

AI 从静态推理向动态交互演进，Agent 能调用 LLM、访问数据库、调用 API、执行任务。当前 LLM 与数据库之间缺少标准化交互协议，每个数据源都需要自定义实现。

MCP（Model Context Protocol，模型上下文协议）为解决这一问题设计的标准化框架，使 LLM 可以与外部数据库、API 和工具高效交互。

### KingbaseES + MCP + LLM 架构

<div align="left">
  <img src="./imgs/readme_framework.drawio.png" alt="readme_framework_01">
</div>




MCP Server 作为 AI 工具与 KingbaseES 之间的桥梁：

- **AI 客户端** 发送自然语言请求（如"找出最慢的查询"）
- **MCP Server** 解析请求，调用对应工具
- **KingbaseES** 执行查询并返回结果
- **AI 客户端** 展示返回结果并提供相关分析

## 产品特性

- **结构探索**：列出 schema、表、视图，查看列/约束/索引详情
- **SQL 执行**：执行任意 SQL；`restricted` 为 AST 白名单**受限**模式
- **执行计划分析**：EXPLAIN / EXPLAIN ANALYZE，支持假设索引模拟
- **索引优化**：基于代价模型 DTA 算法，从查询负载中推荐索引
- **健康检查**：7 项检查 — 索引、连接、vacuum、序列、复制、缓存、约束
- **慢查询分析**：按总耗时/均值耗时/资源消耗排序的 Top N 慢查询
- **多传输方式**：Stdio、SSE、Streamable HTTP

## 功能说明

### Prompts

本项目不预定义 Prompt 模板，AI 通过自然语言对话即可触发数据库操作。

### Tools

| Tool                       | 说明                                                                                | 参数                                              |
|----------------------------|-----------------------------------------------------------------------------------|-------------------------------------------------|
| `list_schemas`             | 列出所有 schema，并区分系统 schema 与用户 schema                                               | 无                                               |
| `list_objects`             | 列出指定 schema 下的表、视图、序列和扩展                                                          | `schema_name`, `object_type`                    |
| `get_object_details`       | 查看表/视图的列定义、约束和索引详情                                                                | `schema_name`, `object_name`, `object_type`     |
| `execute_sql`              | 执行 SQL；`restricted` 仅允许白名单内的只读语句（如 `SELECT`、不带 `ANALYZE` 的 `EXPLAIN`、`SHOW`），禁止 `VACUUM`、`ANALYZE` 和 `CREATE EXTENSION` | `sql`                                           |
| `explain_query`            | 执行 `EXPLAIN` / `EXPLAIN ANALYZE`，支持假设索引模拟                                         | `sql`, `analyze`, `hypothetical_indexes`        |
| `analyze_workload_indexes` | 基于 `sys_stat_statements` 的工作负载推荐索引                                                | `max_index_size_mb`, `method`                   |
| `analyze_query_indexes`    | 对指定 SQL 列表推荐索引（最多 10 条）                                                           | `queries`, `max_index_size_mb`, `method`        |
| `analyze_db_health`        | 执行 7 项数据库健康检查；支持单项、多项（逗号分隔）或全部检查                                                  | `health_type`（如 `index`、`index,buffer` 或 `all`） |
| `get_top_queries`          | 返回 Top N 慢查询（按 `resources`、`mean_time` 或 `total_time` 排序）                         | `sort_by`, `limit`                              |

## 前提条件

- KingbaseES V8R6+ 运行实例

  > **注意：**
  >
  > 当前版本暂不支持使用容器部署测试，数据库需要先手动安装部署。
  >
  > 数据库安装包可从 [Kingbase 官网下载页面](https://www.kingbase.com.cn/download.html)获取，数据库可按照 [KingbaseES 产品手册](https://docs.kingbase.com.cn/cn/KES-V9R1C10/install/01-install-intr) 说明安装部署。

  **相关功能需要以下扩展(非必须，不安装会导致部分性能优化功能不可用)：**

  | 扩展                  | 依赖的功能                              | 安装命令                                |
  | --------------------- | --------------------------------------- | --------------------------------------- |
  | `sys_hypo`            | 假设索引模拟（explain_query、索引分析） | `CREATE EXTENSION sys_hypo;`            |
  | `sys_stat_statements` | 慢查询追踪、工作负载分析                | `CREATE EXTENSION sys_stat_statements;` |

- Python 3.12+

## 安装部署

### 1. 克隆仓库

```bash
git clone https://gitee.com/king-db/kes-mcp-server.git
cd kes-mcp-server
```

### 2. 安装 uv 包管理器

**Linux：**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows：**

```powershell
irm https://astral.sh/uv/install.ps1 | iex
```

**pip 安装（备选）：**

```bash
pip install uv
```

验证安装：

```bash
uv --version
```

### 3. 创建虚拟环境并安装依赖

```bash
uv venv --python 3.12

# Linux / macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

# 安装依赖
uv pip install .
```

>**注意：**
>
>当前 Kingbase-MCP 依赖的数据库驱动 ksycopg2，在 Pypi 发布平台只发布了 Linux x86_64/Aarch64/Windows版本，其他平台版本是否支持可参考 Kingbase 官网手册说明。非 Pypi 发布包，用户需要自行从 [Kingbase 官网下载页面的 Python 模块](https://www.kingbase.com.cn/download.html#drive) 手动下载安装部署 Ksycopg2驱动，手动部署安装可参考 [KingbaseES 产品手册](https://docs.kingbase.com.cn/cn/KES-V9R1C10/application/client_interface/PYTHON/Ksycopg2/python-1#ksycopg2%E8%BF%9E%E6%8E%A5kingbasees%E6%95%B0%E6%8D%AE%E5%BA%93%E9%85%8D%E7%BD%AE)相关说明。
>
>当前 Mac 或者 Alpine 平台明确不支持，因对应 KingbaseES 数据库驱动不支持相关平台，可使用 psycopg2 来伪装成 Ksycopg2来访问 KingbaseES 数据库。
>
>Ksycopg2最高支持到 Python3.13 版本，创建 uv 环境时需要注意 Python 版本。
>
>当前代码依赖 MCP Python SDK 1.x（`mcp[cli]>=1.25.0,<2`），尚未适配 SDK 2.x。

### 4. 配置 MCP Server

Kingbase-MCP 提供了三种传输方式 Stdio/SSE/Streamable HTTP，配置 MCP Server 时根据需要三者选其一即可：

- Stdio

  客户端启动本地子进程，经标准输入/输出传输 MCP 消息；无需开端口，配置简单，适合本机开发。

- SSE

  MCP Server 以 HTTP 提供服务，客户端连接 `/sse` 接收 Server-Sent Events 推送，请求经 HTTP 发送。

  可远程访问，属较早的 HTTP 传输方案。

- Streamable HTTP

  MCP Server 以 HTTP 提供服务，客户端连接 `/mcp`，在同一条 HTTP 会话中双向传输 MCP 消息。
  
  可远程访问，是当前推荐的 HTTP 传输方式。

#### Stdio 模式

本地输入输出流交互，MCP Server 参考配置如下：

```json
{
  "mcpServers": {
    "kingbase-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/kingbase_mcp",
        "run",
        "kingbase-mcp",
        "--access-mode",
        "restricted"
      ],
      "env": {
        "DATABASE_URI": "kingbase://user:password@host:port/dbname"
      }
    }
  }
}
```

#### SSE 模式

远端启动 MCP Server 服务（需先设置 `DATABASE_URI` ）：

```bash
# Linux
export DATABASE_URI="kingbase://user:password@host:port/dbname"

# Windows
$env:DATABASE_URI = "kingbase://user:password@host:port/dbname"

# 启动 MCP Server 服务
uv run kingbase-mcp --transport sse --sse-host 0.0.0.0 --sse-port 8000
```

MCP Server 参考配置（`type` 必须为 `sse`，路径为 `/sse`）：

```json
{
  "mcpServers": {
    "kingbase-sse": {
      "type": "sse",
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}
```

#### Streamable HTTP 模式

远端启动 MCP Server 服务（需先设置 `DATABASE_URI` ）：

```bash
# Linux
export DATABASE_URI="kingbase://user:password@host:port/dbname"

# Windows
$env:DATABASE_URI = "kingbase://user:password@host:port/dbname"

# 启动 MCP Server 服务
uv run kingbase-mcp --transport streamable-http --streamable-http-host 0.0.0.0 --streamable-http-port 8000
```

MCP Server 参考配置（`type` 必须为 `streamableHttp`，路径为 `/mcp`）：

```json
{
  "mcpServers": {
    "kingbase-http": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

## 配置说明

### 连接参数

Kingbase-MCP 通过两类参数进行配置：

#### 环境变量（配置数据库连接）

| 变量                | 必填                         | 说明                                                |
| ------------------- | ---------------------------- | --------------------------------------------------- |
| `DATABASE_URI`      | 是                           | 连接串：`kingbase://user:password@host:port/dbname` |
| `KSYCOPG2_LIB_PATH` | Windows不需要，Linux可选配置 | `libkci.so*` 的路径( Ksycopg2驱动包默认提供)        |

#### 环境变量（LLM 配置，可选）

| 变量                        | 默认值   | 说明                                              |
| --------------------------- | -------- | ------------------------------------------------- |
| `KINGBASE_MCP_LLM_MODEL`    | `gpt-4o` | LLM 模型名称                                      |
| `KINGBASE_MCP_LLM_BASE_URL` |          | LLM API 基础 URL（留空使用 OpenAI 默认地址）       |
| `KINGBASE_MCP_LLM_API_KEY`  |          | LLM API Key（留空使用 `OPENAI_API_KEY` 环境变量） |

连接串格式：

```
kingbase://user:password@host:port/dbname
```

> 注意：
>
> `KSYCOPG2_LIB_PATH` 非必须配置，Linux 下可能出现 `libkci.so*` 找不到的报错，此时可修改配置参数或者环境变量解决。
>
> 对应 libkci 库会通过 Ksycopg2驱动包提供，Ksycopg2一般会安装在对应 `Python安装路径/site-packages/ksycopg2`，uv 环境下 Ksycopg2会安装在 `path/to/mcp_server/kingbase-mcp/.venv/lib/python3.12/site-packages/ksycopg2`。
>
> 配置参数（以 Stdio 配置为例）：
>
> ```json
> {
>   "mcpServers": {
>     "kingbase-mcp": {
>       "command": "uv",
>       "args": [
>         "--directory",
>         "path/to/kingbase_mcp",
>         "run",
>         "kingbase-mcp",
>         "--access-mode",
>         "restricted"
>       ],
>       "env": {
>         "DATABASE_URI": "kingbase://user:password@host:port/dbname",
>         "KSYCOPG2_LIB_PATH": "path/to/ksycopg2"
>        }
>      }
>   }
> }
> ```
>
> 环境变量：
>
> ```bash
> export KSYCOPG2_LIB_PATH=path/to/ksycopg2
> ```

#### CLI 参数（配置服务行为）

| 参数                     | 默认值         | 功能说明                     | 可配置参数值                      |
| ------------------------ | -------------- | ---------------------------- | --------------------------------- |
| `--access-mode`          | `restricted` | SQL 访问模式                 | `unrestricted`、`restricted`      |
| `--transport`            | `stdio`        | MCP 传输方式                 | `stdio`、`sse`、`streamable-http` |
| `--sse-host`             | `localhost`    | SSE 服务绑定地址             | 任意可监听地址                    |
| `--sse-port`             | `8000`         | SSE 服务监听端口             | `1-65535` 的整数                  |
| `--streamable-http-host` | `localhost`    | Streamable HTTP 服务绑定地址 | 任意可监听地址                    |
| `--streamable-http-port` | `8000`         | Streamable HTTP 服务监听端口 | `1-65535` 的整数                  |

### 访问模式

| 模式             | 说明                             | 使用场景   |
|----------------|--------------------------------|--------|
| `restricted`   | AST 白名单**受限**模式：仅允许只读 SQL，禁止 DML、DDL 和维护语句，30s 超时 | 生产环境受限访问 |
| `unrestricted` | 允许所有 SQL（DDL + DML）            | 开发调试   |

### 配置示例

以 TRAE SOLO CN 版本为例，登录用户后，依次点击左下角的用户名 -> 设置 -> MCP，如下图所示：

<div align="left">
  <img src="./imgs/readme_config_trae_01.png" alt="readme_config_trae_01">
</div>

点击添加按钮，将以下 MCP Server 配置项修改成实际情况后填入，如下图所示：

<div align="left">
  <img src="./imgs/readme_config_trae_02.png" alt="readme_config_trae_02">
</div>

连接数据库成功后，会加载对应工具，如下图所示：

<div align="left">
  <img src="./imgs/readme_config_trae_03.png" alt="readme_config_trae_03">
</div>

## 使用说明

以下示例基于 TRAE 实际交互演示，展示 Kingbase-MCP 使用示例。

### 示例 1：连接数据库

```
Q: 调用kingbase-mcp，连接数据库
```

<div align="left">
  <img src="./imgs/readme_example_trae_01.png" alt="readme_example_trae_01">
</div>

### 示例 2：列出所有表

```
Q: 列出 public schema 下所有的表
```

<div align="left">
  <img src="./imgs/readme_example_trae_02.png" alt="readme_example_trae_02">
</div>

### 示例 3：查看表结构

```
Q: 查看 orders 表的结构
```

<div align="left">
  <img src="./imgs/readme_example_trae_03.png" alt="readme_example_trae_03">
</div>

### 示例 4：自然语言查询

```
Q: 查询本月销售额前 5 的商品
```

<div align="left">
  <img src="./imgs/readme_example_trae_04.png" alt="readme_example_trae_04">
</div>

### 示例 5：执行计划分析

```
Q: 分析这个查询：SELECT * FROM orders WHERE user_id = 123 AND status = 'pending'
```

<div align="left">
  <img src="./imgs/readme_example_trae_05.png" alt="readme_example_trae_05">
</div>

### 示例 6：假设索引模拟

```
Q: 如果在 (user_id, status) 上加索引会怎样？
```

<div align="left">
  <img src="./imgs/readme_example_trae_06.png" alt="readme_example_trae_06">
</div>

### 示例 7：索引优化建议

```
Q: 分析一下数据库最近的查询负载，帮我推荐索引
```

<div align="left">
  <img src="./imgs/readme_example_trae_07.png" alt="readme_example_trae_07">
</div>

### 示例 8：健康检查

```
Q: 检查一下数据库健康状况
```

<div align="left">
  <img src="./imgs/readme_example_trae_08.png" alt="readme_example_trae_08">
</div>

### 示例 9：慢查询排查

```
Q: 找出最近最耗时的 5 条查询
```

<div align="left">
  <img src="./imgs/readme_example_trae_09.png" alt="readme_example_trae_09">
</div>

## 安全说明

- **Restricted 模式**：AST 白名单验证；仅允许白名单内的只读语句。禁止 DML、DDL 和维护语句，包括 `VACUUM`、`ANALYZE` 与 `CREATE EXTENSION`；执行层另有只读事务约束（`SET TRANSACTION READ ONLY`）
- **30 秒超时**：防止长时间查询阻塞
- **白名单函数**：500+ 允许函数，80+ 允许扩展
- **连接池上限**：最大 5 个连接

**说明：** `restricted` 是严格只读模式。需要执行 `VACUUM`、`ANALYZE`、`CREATE EXTENSION` 或其它写操作时，请显式使用 `unrestricted` 模式并配置具备相应权限的数据库用户。

**建议：**

- 生产环境使用 `restricted` 模式
- 使用最小权限数据库用户；`restricted` 模式下建议仅授予查询所需权限

## 开发与测试

### 运行测试

项目使用 `pytest` 运行单元测试。部分测试需要连接真实的 KingbaseES 数据库。

**仅运行单元测试（无需数据库连接）：**

```bash
uv run pytest tests/unit --ignore=tests/unit/explain/test_explain_plan_real_db.py --ignore=tests/unit/database_health/test_database_health_tool.py -v
```

**运行全部测试（需配置 `DATABASE_URI`）：**

```bash
# Linux / macOS
export DATABASE_URI="kingbase://user:password@host:port/dbname"
uv run pytest -v

# Windows
$env:DATABASE_URI = "kingbase://user:password@host:port/dbname"
uv run pytest -v
```

### 代码检查

```bash
# Ruff lint + format
uv run ruff check .
uv run ruff format .

# Pyright 类型检查
uv run pyright
```

### 快速开发

```bash
# 使用 justfile 快捷命令
just test    # 运行测试
just dev     # 启动 MCP Server（stdio 模式）
just build   # 构建发行包
```

## 项目结构

```
kingbase-mcp/
├── src/
│   └── kingbase_mcp/                      核心源码目录
│       ├── server.py                      MCP Server 入口、工具注册与 CLI 参数解析
│       ├── artifacts.py                   执行计划结果数据模型定义
│       ├── sql/                           数据库驱动与 SQL 安全控制
│       │   ├── sql_driver.py              连接池与 SQL 执行封装
│       │   ├── safe_sql.py                AST 白名单校验与受限执行约束
│       │   ├── bind_params.py             $N 占位符与统计信息解析
│       │   ├── index.py                   索引定义数据结构
│       │   └── extension_utils.py         扩展可用性与版本检测
│       ├── explain/
│       │   └── explain_plan.py            执行计划分析与假设索引模拟
│       ├── index/                         索引推荐与优化实现
│       │   ├── dta_calc.py                DTA 代价模型优化器
│       │   ├── llm_opt.py                 LLM 辅助索引推荐
│       │   ├── index_opt_base.py          索引优化通用基类与流程编排
│       │   └── presentation.py            索引优化结果格式化输出
│       ├── top_queries/
│       │   └── top_queries_calc.py        慢查询提取与排序分析
│       └── database_health/               数据库健康检查（7 类）
│           ├── database_health.py         健康检查路由分发入口
│           ├── index_health_calc.py       无效/重复/膨胀索引检查
│           ├── connection_health_calc.py  连接利用率检查
│           ├── vacuum_health_calc.py      事务 ID 回卷风险检查
│           ├── sequence_health_calc.py    序列耗尽风险检查
│           ├── replication_calc.py        复制延迟与复制槽检查
│           ├── buffer_health_calc.py      缓存命中率检查
│           └── constraint_health_calc.py  无效约束检查
└── tests/
    ├── conftest.py                        测试工具及初始化
    └── unit/                              单元测试用例
```

## 许可证

MIT许可证，详见 [LICENSE](LICENSE) 。