Skip to main content
Glama
kingbase-mcp-server

kingbase-mcp-server

by NekoTarou

KingBase MCP Server

License Build & Test npm version npm downloads Node.js Version MCP Badge

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

Related 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

SKIP_CONFIRM

跳过写操作确认(见下方说明)

false

权限模式

通过 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)工具使用 MCP Elicitation 机制进行用户确认:

  • 当工具被调用时,服务端通过 elicitation 在协议层面阻塞等待用户确认

  • 客户端会弹出确认对话框,用户必须明确点击确认/拒绝后操作才会继续

  • AI 助手无法绕过此确认流程,确保数据安全

⚠️ 客户端不支持 Elicitation 时:如果你的 MCP 客户端不支持 Elicitation(如旧版本客户端),写操作将默认拒绝执行并提示错误。如果你了解风险并希望跳过确认,可以设置环境变量 SKIP_CONFIRM=true。

⚠️ 警告:设置 SKIP_CONFIRM=true 将跳过所有 DML/DDL 操作的用户确认,AI 助手将直接执行写操作,请自行承担风险!

配置示例

# 只读模式(默认,推荐用于日常查询)
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

  • Secure confirmation for write operations via MCP Elicitation (with two-phase fallback)

  • Auto schema qualification for table names

  • Parameterized queries for safe value substitution

See above sections for detailed documentation (in Chinese).

License

MIT

Available Tools

11 tools
kb_describe_tableDescribe TableA
Read-onlyIdempotent

Get detailed structure of a table or view, including columns, types, constraints, and comments.

Args:

  • table (string): Table or view name

  • schema (string, optional): Schema name, defaults to DB_SCHEMA env or 'public'

Returns: Table structure with column names, data types, nullable, defaults, and comments.

Inputs: table (required), schema.

kb_executeExecute DMLA
Destructive

Execute a DML statement (INSERT, UPDATE, DELETE) against the KingBase database.

Returns the number of affected rows. Use parameterized queries ($1, $2, ...) for safe value substitution.

🔑 Auto-schema feature: Unqualified table names (without schema prefix) are automatically qualified with the configured schema (DB_SCHEMA env var). You can optionally override this with the 'schema' parameter.

Args:

  • sql (string): The DML statement to execute

  • params (array, optional): Parameter values for $1, $2, ... placeholders

  • schema (string, optional): Override the default schema for auto-qualifying table names

Returns: Number of rows affected by the operation.

Examples:

  • sql: "UPDATE users SET status = $1 WHERE id = $2", params: ["inactive", 123]

  • sql: "INSERT INTO users (name, email) VALUES ($1, $2)", params: ["John", "john@example.com"]

  • sql: "DELETE FROM logs WHERE created_at < $1", params: ["2024-01-01"]

Inputs: sql (required), params, schema.

kb_execute_ddlExecute DDLA
Destructive

Execute a DDL statement (CREATE, ALTER, DROP, TRUNCATE, etc.) against the KingBase database.

WARNING: DDL operations modify database structure and can be destructive. DROP and TRUNCATE operations are irreversible.

🔑 Auto-schema feature: Unqualified table names (without schema prefix) are automatically qualified with the configured schema (DB_SCHEMA env var). You can optionally override this with the 'schema' parameter.

Args:

  • sql (string): The DDL statement to execute

  • schema (string, optional): Override the default schema for auto-qualifying table names

Returns: Confirmation message. For dangerous operations (DROP/TRUNCATE/CASCADE), a warning is included.

Examples:

  • sql: "CREATE TABLE test (id SERIAL PRIMARY KEY, name VARCHAR(100))"

  • sql: "ALTER TABLE users ADD COLUMN phone VARCHAR(20)"

  • sql: "CREATE INDEX idx_users_email ON users(email)"

Inputs: sql (required), schema.

kb_explainExplain QueryA
Idempotent

Get the execution plan for a SQL query using EXPLAIN.

Use this to analyze query performance, identify full table scans, and optimize queries.

Args:

  • sql (string): The SQL query to explain

  • analyze (boolean, default false): If true, actually executes the query (EXPLAIN ANALYZE) for real timing data

  • format ('text' | 'json' | 'yaml'): Output format (default: 'text')

Returns: Query execution plan showing scan types, costs, and join strategies.

Examples:

  • sql: "SELECT * FROM users WHERE email = 'test@example.com'"

  • sql: "SELECT u., o. FROM users u JOIN orders o ON u.id = o.user_id", analyze: true

Inputs: sql (required), format, analyze.

kb_list_constraintsList ConstraintsA
Read-onlyIdempotent

List all constraints (PK, FK, UNIQUE, CHECK) on a table.

Args:

  • table (string): Table name

  • schema (string, optional): Schema name, defaults to DB_SCHEMA env or 'public'

Returns: List of constraints with name, type, columns, and referenced table (for FK).

Inputs: table (required), schema.

kb_list_indexesList IndexesA
Read-onlyIdempotent

List all indexes on a table including columns, uniqueness, and index type.

Args:

  • table (string): Table name

  • schema (string, optional): Schema name, defaults to DB_SCHEMA env or 'public'

Returns: List of indexes with name, columns, uniqueness, and method (btree/hash/gin/gist).

Inputs: table (required), schema.

kb_list_schemasList SchemasA
Read-onlyIdempotent

List all schemas in the KingBase database.

Returns schema names excluding internal PostgreSQL/KingBase system schemas.

Args: None

Returns: List of schema names with their owners.

Inputs: no named parameters.

kb_list_tablesList TablesA
Read-onlyIdempotent

List all tables and/or views in a schema.

Args:

  • schema (string, optional): Schema name, defaults to DB_SCHEMA env or 'public'

  • type ('table' | 'view' | 'all'): Filter by type (default: 'all')

Returns: List of tables/views with their type, owner, and estimated row count.

Inputs: type, schema.

kb_queryExecute QueryA
Read-onlyIdempotent

Execute a read-only SQL query (SELECT/WITH/SHOW) against the KingBase database.

Returns query results as a formatted table. Use parameterized queries ($1, $2, ...) for safe value substitution.

Only read-only statements are allowed. For INSERT/UPDATE/DELETE use kb_execute; for DDL use kb_execute_ddl.

🔑 Auto-schema feature: Unqualified table names (without schema prefix) are automatically qualified with the configured schema (DB_SCHEMA env var). You can optionally override this with the 'schema' parameter.

Args:

  • sql (string): The SELECT query to execute

  • params (array, optional): Parameter values for $1, $2, ... placeholders

  • schema (string, optional): Override the default schema for auto-qualifying table names

Returns: Formatted table of query results with row count.

Examples:

  • sql: "SELECT * FROM biz_cm_attachment LIMIT 5" (auto-qualified with configured schema)

  • sql: "SELECT * FROM users WHERE status = $1", params: ["active"]

  • sql: "SELECT * FROM public.sys_user" (explicit schema, not auto-qualified)

Inputs: sql (required), params, schema.

kb_table_dataPreview Table DataA
Read-onlyIdempotent

Preview data from a table with optional filtering and pagination.

A convenient shortcut for common SELECT operations without writing full SQL.

Args:

  • table (string): Table name

  • schema (string, optional): Schema name, defaults to DB_SCHEMA env or 'public'

  • limit (number, default 100, max 1000): Number of rows

  • offset (number, default 0): Rows to skip

  • where (string, optional): WHERE condition (without WHERE keyword)

  • order_by (string, optional): ORDER BY clause (without ORDER BY keyword)

Returns: Formatted table of row data with total count.

Examples:

  • table: "users", limit: 10, where: "status = 'active'", order_by: "created_at DESC"

  • table: "orders", limit: 50, offset: 100

Inputs: table (required), limit, where, offset, +2 more.

kb_table_statsTable StatisticsA
Read-onlyIdempotent

Get storage and usage statistics for a table, including row count, size, and dead tuples.

Args:

  • table (string): Table name

  • schema (string, optional): Schema name, defaults to DB_SCHEMA env or 'public'

Returns: Table size, row count, index size, dead tuples, and last vacuum/analyze times.

Inputs: table (required), schema.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct database operation: schema listing, table description, read-only queries, DML, DDL, stats, etc. Even the overlapping kb_query and kb_table_data are clearly differentiated by generality vs. convenience with pagination.

    Naming Consistency5/5

    All tools start with the 'kb_' prefix, and most follow a verb_noun pattern (e.g., kb_list_schemas, kb_describe_table). The few single-verb names (kb_query, kb_execute) are still clear and consistent within the domain.

    Tool Count5/5

    11 tools is an ideal size for a database MCP server, covering all essential operations without overwhelming the agent.

    Completeness5/5

    The tool set provides full lifecycle coverage: schema inspection, table metadata, indexes, constraints, stats, explain plans, and both DML and DDL execution via kb_execute and kb_execute_ddl. The convenient kb_table_data tool fills a common use case.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for DaMeng database, enabling AI assistants to execute SQL queries, list tables, describe table structures, and retrieve schema information.
      42 npm
      7
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Cursor-integrated MCP server for Kingbase (人大金仓) databases, enabling schema queries, document generation, and SQL execution with configurable security modes (readonly, limited_write, full_access).
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A unified MCP server for querying and managing multiple database types (PostgreSQL, MySQL, SQL Server, etc.) via natural language through AI assistants.
      GPL 3.0
    • A
      license
      A
      quality
      D
      maintenance
      MCP server enabling AI assistants to connect and query Dameng DM8 databases via JDBC. Supports SQL queries, listing tables, and describing schemas.
      3
      34 npm
      MIT