kingbase-mcp-server

v1.0.4

Published

4 hours ago

MCP server for KingBase (PostgreSQL-compatible) database operations

Downloads

311

0High
0Medium
0Low

nekoutarou

mcp mcp-server kingbase database postgresql model-context-protocol ai llm

KingBase MCP Server

English | 中文

直连 KingBase（PostgreSQL 兼容）数据库的 MCP Server，让 AI 助手（Claude 等）能够直接查询和管理 KingBase 数据库。

快速使用

无需克隆代码，直接在 MCP 客户端中配置即可使用：

{
  "mcpServers": {
    "kingbase": {
      "command": "npx",
      "args": ["-y", "kingbase-mcp-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "54321",
        "DB_USER": "system",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "kingbase",
        "DB_SCHEMA": "public",
        "ACCESS_MODE": "readonly"
      }
    }
  }
}

也可以全局安装后使用：

npm install -g kingbase-mcp-server
kingbase-mcp-server

功能

| Tool | 说明 | 类型 | | --------------------- | ---------------------------------- | ---- | | kb_query | 执行只读查询 (SELECT/WITH/SHOW) | 只读 | | kb_execute | 执行 DML (INSERT/UPDATE/DELETE) | 读写 | | kb_execute_ddl | 执行 DDL (CREATE/ALTER/DROP) | 读写 | | kb_list_schemas | 列出所有 schema | 只读 | | kb_list_tables | 列出表和视图 | 只读 | | kb_describe_table | 查看表结构（列、类型、约束、注释） | 只读 | | kb_list_indexes | 查看索引信息 | 只读 | | kb_list_constraints | 查看约束信息 | 只读 | | kb_explain | 查看执行计划 (EXPLAIN) | 只读 | | kb_table_data | 预览表数据（带分页和过滤） | 只读 | | kb_table_stats | 查看表统计信息（大小、行数等） | 只读 |

提示词 (Prompts)

| Prompt | 说明 | | -------------------- | ------------------------------------- | | kb_query_prompt | 查询助手：描述需求，自动构造 SQL 查询 | | kb_schema_overview | Schema 概览：获取数据库结构的全面分析 |

资源 (Resources)

| URI | 说明 | | ------------------- | ------------------------------------------ | | kingbase://config | 当前数据库连接配置（不含密码等敏感信息） | | kingbase://status | 服务器运行状态（版本、连接状态、运行时间） |

环境变量

| 变量 | 说明 | 默认值 | | ------------- | --------------------------- | ----------- | | DB_HOST | 数据库主机 | localhost | | DB_PORT | 数据库端口 | 54321 | | DB_USER | 用户名 | system | | DB_PASSWORD | 密码 | (空) | | DB_NAME | 数据库名 | kingbase | | DB_SCHEMA | 默认 schema | public | | TRANSPORT | 传输模式：stdio 或 http | stdio | | MCP_PORT | HTTP 模式监听端口 | 3000 | | MCP_HOST | HTTP 模式监听地址 | 0.0.0.0 | | ACCESS_MODE | 权限模式（见下方说明） | readonly |

权限模式

通过 ACCESS_MODE 环境变量控制数据库操作权限，分为 4 个递增级别：

| 级别 | 值 | 允许的操作 | | -------- | ------------------ | ------------------------------------------------------- | | 只读 | readonly（默认） | SELECT 查询、查看 schema/表结构/索引/约束/统计/执行计划 | | 允许修改 | readwrite | 只读 + INSERT / UPDATE | | 允许删除 | full | 读写 + DELETE | | 管理员 | admin | 完全权限 + DDL（CREATE / ALTER / DROP / TRUNCATE） |

默认为 readonly（只读模式），防止误操作。根据实际需要调整。

二次确认机制

kb_execute（DML）和 kb_execute_ddl（DDL）工具内置二次确认：

首次调用（不传 confirmed 或 confirmed: false）→ 不执行 SQL，返回操作预览和确认提示
确认调用（confirmed: true）→ 真正执行 SQL

这确保 LLM 在执行写操作前必须向用户确认，避免意外修改数据。

配置示例

# 只读模式（默认，推荐用于日常查询）
ACCESS_MODE=readonly

# 允许增改（适用于数据维护）
ACCESS_MODE=readwrite

# 允许删除（适用于数据清理）
ACCESS_MODE=full

# 管理员模式（适用于 DDL 操作，如建表/改表）
ACCESS_MODE=admin

传输模式

stdio 模式（默认）

适用于本地使用，客户端直接启动 MCP Server 进程。

HTTP 模式

适用于远程部署，团队成员通过网络连接。使用 MCP Streamable HTTP 传输协议。

启动 HTTP 模式：

TRANSPORT='http' MCP_PORT='3000' DB_HOST='你的数据库地址' DB_PASSWORD='你的密码' node dist/index.js
# 或
npm run start:http

验证：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

在 Claude Code 中使用

stdio 模式（推荐）

编辑 ~/.claude.json，在对应的空间下添加，或者在当前目录中创建.mcp.json文件，添加如下内容：

{
  "mcpServers": {
    "kingbase": {
      "command": "npx",
      "args": ["-y", "kingbase-mcp-server"],
      "env": {
        "DB_HOST": "你的数据库地址",
        "DB_PORT": "54321",
        "DB_USER": "system",
        "DB_PASSWORD": "你的密码",
        "DB_NAME": "数据库名",
        "DB_SCHEMA": "public",
        "ACCESS_MODE": "readonly"
      }
    }
  }
}

HTTP 模式（远程连接）

在服务器上启动 HTTP 模式后，客户端配置：

{
  "mcpServers": {
    "kingbase": {
      "url": "http://你的服务器地址:3000/mcp"
    }
  }
}

构建

npm install
npm run build

配置文件

项目支持 .env 配置文件，避免在 shell 中直接传入含特殊字符的密码导致解析失败。

# 复制模板
cp .env.example .env

# 编辑配置（密码中的特殊字符无需转义）
vi .env

.env 文件示例：

DB_HOST=192.168.1.100
DB_PORT=54321
DB_USER=system
DB_PASSWORD=P@ss(w0rd)!#$
DB_NAME=mydb
DB_SCHEMA=public
TRANSPORT=http
MCP_PORT=3000
ACCESS_MODE=readonly

配置好后直接启动即可，无需在命令行传递环境变量：

node dist/index.js
# 或
npm start

.env 已在 .gitignore 中，不会被提交到仓库。命令行传入的环境变量优先级高于 .env 文件。

服务器部署（HTTP 模式）

1. 安装

# 方式一：npm 全局安装（推荐）
npm install -g kingbase-mcp-server

# 方式二：从源码安装
git clone https://github.com/NekoTarou/kingbase-mcp-server.git
cd kingbase-mcp-server
npm install
npm run build

2. 直接启动

TRANSPORT='http' \
MCP_PORT='3000' \
ACCESS_MODE='readonly' \
DB_HOST='192.168.1.100' \
DB_PORT='54321' \
DB_USER='system' \
DB_PASSWORD='your_password' \
DB_NAME='mydb' \
node dist/index.js

3. 使用 systemd 管理（推荐）

创建环境变量文件 /etc/kingbase-mcp-server.env：

TRANSPORT=http
MCP_PORT=3000
MCP_HOST=0.0.0.0
ACCESS_MODE=readonly
DB_HOST=192.168.1.100
DB_PORT=54321
DB_USER=system
DB_PASSWORD=your_password
DB_NAME=mydb
DB_SCHEMA=public

创建服务文件 /etc/systemd/system/kingbase-mcp.service：

[Unit]
Description=KingBase MCP Server
After=network.target

[Service]
Type=simple
EnvironmentFile=/etc/kingbase-mcp-server.env
WorkingDirectory=/opt/kingbase-mcp-server
ExecStart=/usr/bin/node dist/index.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl daemon-reload
sudo systemctl enable kingbase-mcp
sudo systemctl start kingbase-mcp
sudo systemctl status kingbase-mcp   # 查看状态
sudo journalctl -u kingbase-mcp -f   # 查看日志

4. 验证

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

成功会返回 JSON 响应，response header 中包含 mcp-session-id。

5. 安全提示

当前未内置认证机制。如果服务暴露在公网，建议：

通过防火墙限制访问来源 IP
在前面加 nginx 反向代理 + 基础认证
后续可按需添加 OAuth 认证

English

MCP (Model Context Protocol) server for KingBase — a PostgreSQL-compatible enterprise database widely used in Chinese government and enterprise environments.

Quick Start

{
  "mcpServers": {
    "kingbase": {
      "command": "npx",
      "args": ["-y", "kingbase-mcp-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "54321",
        "DB_USER": "system",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "kingbase",
        "ACCESS_MODE": "readonly"
      }
    }
  }
}

Features

11 database tools: query, DML, DDL, schema inspection, statistics
2 prompts: query helper, schema overview
2 resources: database config, server status
Two transport modes: stdio (local) and Streamable HTTP (remote)
Fine-grained access control: readonly / readwrite / full / admin
Two-phase confirmation for write operations
Auto schema qualification for table names
Parameterized queries for safe value substitution

See above sections for detailed documentation (in Chinese).

License

MIT