MCP openGauss Server
一个用于 openGauss 数据库的 MCP (Model Context Protocol) 服务器，提供安全的只读数据库查询功能。
功能特性
- ✅ 安全的只读查询：仅允许 SELECT、SHOW、DESCRIBE、EXPLAIN 等只读操作
- ✅ 查询优化分析：支持 EXPLAIN（执行计划）与 EXPLAIN ANALYZE（真实耗时）
- ✅ 完整的表管理：列出表、查询表结构、执行自定义查询
- ✅ 可选写入能力（默认禁用）：可通过配置开启 INSERT/UPDATE，并要求每次写入二次确认
- ✅ openGauss 原生支持：基于
node-opengauss驱动，完全兼容 openGauss 特性 - ✅ PostgreSQL 兼容：利用 openGauss 对 PostgreSQL 的兼容性
- ✅ 类型安全：使用 TypeScript 和 Zod 进行参数验证
安装
1. 安装依赖
npm install2. 配置环境变量
创建 .env 文件：
# openGauss 数据库配置
OPENGAUSS_HOST=localhost
OPENGAUSS_PORT=5432
OPENGAUSS_DATABASE=postgres
OPENGAUSS_USER=your_username
OPENGAUSS_PASSWORD=your_password
OPENGAUSS_SCHEMA=public
# 高风险：是否启用写入能力（默认 false）
OPENGAUSS_ENABLE_WRITE=false3. 构建项目
npm run build使用方法
开发模式
npm run dev生产模式
npm start在 MCP 客户端中配置
在你的 MCP 客户端配置文件中添加：
方式 1：使用 npx 启动（推荐：统一适配 Claude Desktop / Cursor / Codex）
前提：已全局安装mcp-opengauss-server（npm install -g mcp-opengauss-server）。 - macOS/Linux：command使用npx- Windows：command建议使用npx.cmd- 如遇到 “npx 找不到包”，可先去掉--no-install（允许 npx 自动下载），或改回直接使用mcp-opengauss命令。
常见配置文件位置：
- Cursor：
~/.cursor/mcp.json（Windows：%USERPROFILE%\\.cursor\\mcp.json） - Claude Desktop：
~/Library/Application Support/Claude/claude_desktop_config.json（Windows：%APPDATA%\\Claude\\claude_desktop_config.json） - Codex：在 Codex 的
mcpServers配置中加入同样片段即可（不同安装形态路径可能不同）
macOS / Linux
{
"mcpServers": {
"opengauss": {
"command": "npx",
"args": [
"--no-install",
"mcp-opengauss-server",
"--host",
"localhost",
"--port",
"5432",
"--user",
"your_username",
"--password",
"your_password",
"--database",
"postgres",
"--schema",
"public"
]
}
}
}启用写入功能（可选，高风险）
如需启用数据写入功能（INSERT/UPDATE），在 args 中添加 --enable-write 参数：
{
"mcpServers": {
"opengauss": {
"command": "npx",
"args": [
"--no-install",
"mcp-opengauss-server",
"--host",
"localhost",
"--port",
"5432",
"--user",
"your_username",
"--password",
"your_password",
"--database",
"postgres",
"--schema",
"public",
"--enable-write"
]
}
}
}Windows
{
"mcpServers": {
"opengauss": {
"command": "npx.cmd",
"args": [
"--no-install",
"mcp-opengauss-server",
"--host",
"localhost",
"--port",
"5432",
"--user",
"your_username",
"--password",
"your_password",
"--database",
"postgres",
"--schema",
"public"
]
}
}
}Windows 启用写入功能
{
"mcpServers": {
"opengauss": {
"command": "npx.cmd",
"args": [
"--no-install",
"mcp-opengauss-server",
"--host",
"localhost",
"--port",
"5432",
"--user",
"your_username",
"--password",
"your_password",
"--database",
"postgres",
"--schema",
"public",
"--enable-write"
]
}
}
}方式 2：使用本地构建文件（无需 npx）
{
"mcpServers": {
"opengauss": {
"command": "node",
"args": ["/path/to/mcp-opengauss-server/dist/index.js"],
"env": {
"OPENGAUSS_HOST": "localhost",
"OPENGAUSS_PORT": "5432",
"OPENGAUSS_DATABASE": "postgres",
"OPENGAUSS_USER": "your_username",
"OPENGAUSS_PASSWORD": "your_password",
"OPENGAUSS_SCHEMA": "public",
"OPENGAUSS_ENABLE_WRITE": "false"
}
}
}
}启用写入功能（方式 2）
将 OPENGAUSS_ENABLE_WRITE 设置为 "true"：
{
"mcpServers": {
"opengauss": {
"command": "node",
"args": ["/path/to/mcp-opengauss-server/dist/index.js"],
"env": {
"OPENGAUSS_HOST": "localhost",
"OPENGAUSS_PORT": "5432",
"OPENGAUSS_DATABASE": "postgres",
"OPENGAUSS_USER": "your_username",
"OPENGAUSS_PASSWORD": "your_password",
"OPENGAUSS_SCHEMA": "public",
"OPENGAUSS_ENABLE_WRITE": "true"
}
}
}
}可用工具
1. list_tables
列出指定 schema 下的所有表。
参数：
schema(可选): Schema 名称，默认使用配置中的OPENGAUSS_SCHEMA
示例：
{
"schema": "public"
}2. execute_query
执行只读 SQL 查询（SELECT、SHOW、DESCRIBE、EXPLAIN）。
参数：
query(必需): SQL 查询语句schema(可选): Schema 名称
示例：
{
"query": "SELECT * FROM users WHERE id = 16
- **Language**: TypeScript 5.x
- **Database Driver**: node-opengauss 7.x
- **MCP SDK**: @modelcontextprotocol/sdk 1.21+
- **Validation**: Zod 3.x
## 与 DM8 MCP Server 的差异
| 特性 | DM8 | openGauss |
|------|-----|-----------|
| 数据库驱动 | dmdb | node-opengauss |
| 系统表查询 | `ALL_TABLES` | `pg_tables` |
| 表结构查询 | DM8 特定视图 | `information_schema.columns` |
| 连接协议 | DM 原生协议 | PostgreSQL 协议 |
| 兼容模式 | - | A/B/PG 模式 |
## 故障排除
### 连接失败
1. 检查 openGauss 服务是否运行
2. 验证连接参数（主机、端口、用户名、密码）
3. 确认用户有访问数据库的权限
4. 检查防火墙设置
### Schema 不存在
确保配置的 schema 存在：
SELECT schema_name FROM information_schema.schemata;
### 权限不足
确保用户有查询权限：
GRANT SELECT ON ALL TABLES IN SCHEMA public TO your_username;
## 开发
### 运行测试
npm test
### 代码检查
npm run lint
## 项目结构
mcp-opengauss-server/ ├── src/ │ ├── config.ts # 配置管理 │ ├── server.ts # MCP 服务器 │ ├── index.ts # 入口文件 │ ├── cli.ts # CLI 入口 │ ├── tools/ │ │ ├── index.ts # 工具注册 │ │ ├── listTables.ts # 列表工具 │ │ ├── executeQuery.ts # 查询工具 │ │ └── describeTable.ts # 表结构工具 │ └── utils/ │ ├── db.ts # 数据库连接 │ └── validation.ts # 验证工具 ├── tests/ # 测试文件 ├── dist/ # 编译输出 ├── package.json ├── tsconfig.json └── README.md
## openGauss 特性说明
### 与 PostgreSQL 的兼容性
openGauss 基于 PostgreSQL 9.2.4 开发，保留了：
- ✅ libpq 协议兼容
- ✅ PostgreSQL 标准接口
- ✅ pg_tables、information_schema 等系统视图
- ✅ PSQL 客户端兼容
### 主要差异
尽管 openGauss 兼容 PostgreSQL，但在以下方面有所不同：
- 内核经过大量优化（约 74% 代码修改）
- 不支持表继承
- 特有的安全特性和性能优化
- 支持多种兼容模式（A/B/PG）
## 许可证
MIT
## 贡献
欢迎提交 Issue 和 Pull Request！
## 相关项目
- [mcp-dm8-server](../mcp-dm8-server) - DM8 数据库的 MCP 服务器
- [dm-mcp-server](../dm-mcp-server) - DM 数据库的 Go 实现
## 致谢
- openGauss 社区
- node-opengauss 项目
- Model Context Protocol (MCP) 项目