GaussDB MCP

Huawei Cloud GaussDB cloud database MCP server. Built on Huawei's official GaussDB dedicated Node.js driver gaussdb-node, following the MCP 2026-07-28 specification, providing 24 tools and 1 table structure resource covering connection testing, querying, data writing, transactions, metadata, diagnostics and operations, user permissions, etc.

Quick Start

npm install
cp .env.example .env   # Windows: copy .env.example .env 后编辑
# 编辑 .env,填入 GaussDB 实例地址、密码等
npm run build
node build/index.js    # 启动(stdio,供 MCP 客户端拉起)

Requires Node.js ≥ 20.

Related MCP server: mcp-db-assistant

Connection Configuration

All Environment Variables

Intranet Connection Configuration

Used when the application and the GaussDB instance are in the same VPC. SSL is not required (intranet traffic does not leak externally; Huawei Cloud officially defaults to direct intranet connection):

GAUSSDB_HOST=10.0.1.11              # 实例"节点列表"中的内网地址
GAUSSDB_PORT=8000
GAUSSDB_DATABASE=postgres
GAUSSDB_USER=root
GAUSSDB_PASSWORD=你的密码
# 不设置任何 GAUSSDB_SSL_* 变量,保持 GAUSSDB_SSL=0(默认)

Public Network Connection Configuration

Used when the application is not in the instance's VPC and accesses it via an elastic public IP. SSL must be enabled and a CA certificate configured (Huawei Cloud official sslmode=verify-ca approach):

GAUSSDB_HOST=114.114.114.114        # 实例绑定的弹性公网 IP
GAUSSDB_PORT=8000
GAUSSDB_DATABASE=postgres
GAUSSDB_USER=root
GAUSSDB_PASSWORD=你的密码
GAUSSDB_SSL=1
GAUSSDB_SSL_CA=C:/path/to/root.crt   # 华为云控制台下载的 CA 证书(公网连接必需)
GAUSSDB_SSL_REJECT_UNAUTHORIZED=true

Before public network connection, you also need to allow the client's egress IP access to port 8000 in the Huawei Cloud console security group.

How to Add Environment Variables

Two methods, choose either one (when both exist, environment variables take precedence over .env):

1. Project .env file (recommended): Copy .env.example to .env in the project root directory and fill it in. The .env location is anchored to the project root directory, independent of which directory the server is started from — the MCP client can read it when launching build/index.js from any working directory. Write either of the two configurations above directly into .env.

2. MCP client env field: Pass environment variables directly in the mcpServers configuration (see integration examples below), suitable for scenarios where you don't want to put credential files in the project.

For primary/standby deployments, separate multiple node IPs in GAUSSDB_HOST with English commas. The server tries connecting to each in sequence at startup and automatically selects the first available node.

Tool Overview (24 tools)

All tools are annotated with annotations (readOnlyHint/destructiveHint) per the MCP specification, allowing clients to prompt for confirmation on write operations.

Connection and Status

Query and Write

Transactions (explicit handle mode)

Usage: transaction_begin → multiple query/execute (passing the same tx_handle) → transaction_commit or transaction_rollback.

Metadata (read-only)

Diagnostics and Operations (read-only)

Users and Permissions

Resources

MCP Client Integration

After building, register in the client configuration file (using Claude Desktop / Cursor's mcpServers format as an example). Windows uses double backslash paths (E:\\MCP\\GaussDBMCP\\build\\index.js), Linux/macOS uses forward slashes (/home/user/GaussDBMCP/build/index.js).

Intranet Connection Integration

{
  "mcpServers": {
    "gaussdb": {
      "command": "node",
      "args": ["E:\\MCP\\GaussDBMCP\\build\\index.js"],
      "env": {
        "GAUSSDB_HOST": "10.0.1.11",
        "GAUSSDB_PORT": "8000",
        "GAUSSDB_DATABASE": "postgres",
        "GAUSSDB_USER": "root",
        "GAUSSDB_PASSWORD": "你的密码"
      }
    }
  }
}

Intranet connection does not require SSL; simply do not set any GAUSSDB_SSL_* variables.

Public Network Connection Integration

{
  "mcpServers": {
    "gaussdb": {
      "command": "node",
      "args": ["E:\\MCP\\GaussDBMCP\\build\\index.js"],
      "env": {
        "GAUSSDB_HOST": "114.114.114.114",
        "GAUSSDB_PORT": "8000",
        "GAUSSDB_DATABASE": "postgres",
        "GAUSSDB_USER": "root",
        "GAUSSDB_PASSWORD": "你的密码",
        "GAUSSDB_SSL": "1",
        "GAUSSDB_SSL_CA": "C:\\path\\to\\root.crt",
        "GAUSSDB_SSL_REJECT_UNAUTHORIZED": "true"
      }
    }
  }
}

Public network connection must enable SSL and configure a CA certificate, and ensure the security group allows the client's egress IP access to port 8000.

You can also omit env and rely on the .env file in the project root directory (automatically read at server startup, anchored to the project root, independent of the startup directory).

Multi-Tenant Isolation (stream = schema)

GAUSSDB_SEARCH_PATH also serves as the MCP-layer schema whitelist: once configured, access is restricted to the corresponding stream's own schema, and tables of other streams cannot be seen.

MCP-layer interception (reliable, based on structural parameters):

• list_schemas only returns schemas in the whitelist, not leaking other schema names

• list_tables/list_indexes/list_views/list_sequences default to pinning to the first whitelisted schema when no schema is passed, no longer returning all database tables

• describe_table/insert_rows/update_rows/delete_rows with an explicit schema parameter will directly error and reject if it is not in the whitelist

• The table structure resource gaussdb://{schema}/{table}/schema is also subject to the whitelist; cross-schema reads are rejected

Database permission-layer fallback (required, cannot be omitted): execute accepts arbitrary SQL, and the MCP layer does not parse SQL (a hand-written parser will always have bypass paths); although query enforces read-only (first-keyword whitelist + write-keyword blacklist + rejection of multi-statements), side-effect functions in SELECT form (such as pg_terminate_backend, setval) cannot be exhaustively intercepted. Cross-schema access and side-effect functions are guaranteed by GaussDB permissions. Each stream uses an independent restricted account, authorized only for its own schema:

-- 以管理员执行:为 stream 建受限账号,只授予自己 schema 的权限
CREATE USER gycwd_app WITH PASSWORD 'xxx' LOGIN;
REVOKE ALL ON DATABASE postgres FROM PUBLIC;            -- 收紧库级默认权限
GRANT CONNECT ON DATABASE postgres TO gycwd_app;
GRANT USAGE ON SCHEMA gycwd TO gycwd_app;               -- 只给自己的 schema
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA gycwd TO gycwd_app;
-- 该账号未授予其他 schema 的 USAGE,即使手写跨 schema SQL 也会被数据库拒绝

Then in .env set GAUSSDB_USER=gycwd_app, GAUSSDB_SEARCH_PATH=gycwd, with two layers combined: structural entry points intercepted by MCP, arbitrary SQL intercepted by the database.

Security Notes

• stdio server logs are all written to stderr; stdout only carries MCP messages

• Identifiers such as table names/column names/user names in structured tools (insert_rows/update_rows/delete_rows, etc.) are all character-validated, and values always use parameterized placeholders to prevent SQL injection; query/explain_query are free-form SQL entry points, narrowed down by read-only validation and single-statement restrictions (see above)

• delete_rows/update_rows enforce a where condition

• explain_query with analyze=true actually executes the statement, only allowing statements starting with SELECT/WITH and automatically wrapping in a transaction rollback (sequence advancement and function side effects are not rollback-able)

• Statements such as DROP/TRUNCATE can be executed via execute; clients should rely on the destructiveHint annotation for confirmation

• Do not commit .env to version control

Development and Build

npm run build   # tsc 编译到 build/

Source structure: src/config.ts (configuration), src/db.ts (connection pool and transaction handles), src/sql.ts (SQL construction and read-only validation), src/format.ts (result formatting), src/index.ts (MCP server and tool registration).

Once you have a real GaussDB instance: fill in .env → npm run build → node build/index.js and test with any MCP client; or first verify the connection separately: configure env and run the test_connection tool.