GaussDB MCP

华为云 GaussDB 云数据库 MCP 服务器。基于华为官方 GaussDB 専用 Node.js ドライバ gaussdb-node、MCP 2026-07-28 仕様に準拠し、接続テスト、クエリ、データ書き込み、トランザクション、メタデータ、診断・運用、ユーザー権限など 24 個のツールと 1 個のテーブル構造リソースを提供します。

クイックスタート

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

要件:Node.js ≥ 20。

Related MCP server: mcp-db-assistant

接続設定

全環境変数

内網接続設定

アプリと GaussDB インスタンスが同一 VPC 内にある場合に使用します。SSL は不要(内網トラフィックは外部に漏れないため、华为云公式のデフォルトは内網直結):

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

公網接続設定

アプリがインスタンスの VPC 外にあり、弹性公网 IP 経由でアクセスする場合に使用します。SSL を有効化し CA 証明書を設定する必要があります(华为云公式の sslmode=verify-ca 方式):

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

公網接続の前に、华为云コンソールのセキュリティグループでクライアントの送信元 IP の 8000 番ポートへのアクセスを許可する必要があります。

環境変数の追加方法

以下の 2 つの方法のいずれかを選択します(両方存在する場合、環境変数が .env より優先されます):

1. プロジェクトの .env ファイル(推奨):.env.example をプロジェクトルートの .env にコピーして記入します。.env の位置はプロジェクトルートに固定され、サーバーがどのディレクトリから起動されるかとは無関係です——MCP クライアントが任意の作業ディレクトリから build/index.js を起動しても読み取れます。上記 2 つの設定をそのまま .env に記述します。

2. MCP クライアントの env フィールド:mcpServers 設定内で直接環境変数を渡します(下記の接続例を参照)。プロジェクト内に認証情報ファイルを置きたくない場合に適しています。

主備デプロイ時、GAUSSDB_HOST はカンマ区切りで複数ノードの IP を指定します。サーバー起動時に順次接続を試み、最初に利用可能なノードを自動選択します。

ツール一覧(24 個)

すべてのツールは MCP 仕様に従って annotations(readOnlyHint/destructiveHint)が付与されており、クライアントはこれに基づいて書き込み操作時に確認ダイアログを表示できます。

接続と状態

クエリと書き込み

トランザクション(明示的 handle モード)

使用方法:transaction_begin → 複数回の query/execute(同じ tx_handle を渡す)→ transaction_commit または transaction_rollback。

メタデータ(読み取り専用)

診断・運用(読み取り専用)

ユーザーと権限

リソース

MCP クライアント接続

ビルド後、クライアント設定ファイルに登録します(Claude Desktop / Cursor の mcpServers 形式を例とします)。Windows は二重バックスラッシュパス(E:\\MCP\\GaussDBMCP\\build\\index.js)、Linux/macOS はスラッシュ(/home/user/GaussDBMCP/build/index.js)を使用します。

内網接続

{
  "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": "你的密码"
      }
    }
  }
}

内網接続は SSL が不要で、GAUSSDB_SSL_* 変数を一切設定する必要はありません。

公網接続

{
  "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"
      }
    }
  }
}

公網接続は SSL を有効化し CA 証明書を設定する必要があり、セキュリティグループでクライアント送信元 IP の 8000 番ポートを許可する必要があります。

また、env を渡さず、プロジェクトルートの .env ファイルに依存することもできます(サーバー起動時に自動読み込み。プロジェクトルートに固定され、起動ディレクトリとは無関係)。

マルチテナント分離(stream = schema)

GAUSSDB_SEARCH_PATH は同時に MCP 層の schema ホワイトリストとして機能します。設定後、アクセスは対応する stream 自身の schema 内に制限され、他の stream のテーブルは見えません。

MCP 層のインターセプト(信頼性あり、構造パラメータに依存):

• list_schemas はホワイトリスト内の schema のみを返し、他の schema 名を漏らさない

• list_tables/list_indexes/list_views/list_sequences は schema を渡さない場合、デフォルトで最初のホワイトリスト schema に固定され、全データベースのテーブルを返さない

• describe_table/insert_rows/update_rows/delete_rows で明示的に schema を渡す場合、ホワイトリスト外なら直接エラーで拒否

• テーブル構造リソース gaussdb://{schema}/{table}/schema もホワイトリストの制約を受け、スキーマをまたいだ読み取りは拒否される

データベース権限層のフォールバック(必須、省略不可):execute は任意の SQL であり、MCP 層では SQL 解析を行いません(手書きパーサーには必ずバイパス経路が存在)。query は読み取り専用を強制しますが(先頭キーワードのホワイトリスト + 書き込みキーワードのブラックリスト + 複数ステートメント拒否)、SELECT 形式の副作用関数(例:pg_terminate_backend、setval)は網羅的にインターセプトできません。スキーマをまたいだアクセスと副作用関数は GaussDB の権限で保証します。各 stream は独立した制限付きアカウントを使用し、自分の 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 也会被数据库拒绝

その後、.env で GAUSSDB_USER=gycwd_app、GAUSSDB_SEARCH_PATH=gycwd を設定します。2 層が重なり合います:構造エントリは MCP がインターセプト、任意の SQL はデータベースがインターセプトします。

セキュリティ注意事項

• stdio サーバーのログはすべて stderr に書き込まれ、stdout は MCP メッセージのみを運びます

• 構造化ツール(insert_rows/update_rows/delete_rows など)のテーブル名/列名/ユーザー名などの識別子はすべて文字検証を行い、値はすべてパラメータ化プレースホルダーを使用して SQL インジェクションを防止します。query/explain_query は自由 SQL エントリであり、読み取り専用検証と単一ステートメント制限で範囲を絞ります(上記参照)

• delete_rows/update_rows は where 条件を必須とします

• explain_query の analyze=true はステートメントを実際に実行しますが、SELECT/WITH で始まるもののみ許可し、自動的にトランザクションロールバックで包みます(シーケンスの進行、関数の副作用はロールバック不可)

• DROP/TRUNCATE などのステートメントは execute で実行可能です。クライアントは destructiveHint 注記に基づいて確認を行ってください

• .env をバージョン管理リポジトリにコミットしないでください

開発とビルド

npm run build   # tsc 编译到 build/

ソース構造:src/config.ts(設定)、src/db.ts(接続プールとトランザクションハンドル)、src/sql.ts(SQL 構築と読み取り専用検証)、src/format.ts(結果フォーマット)、src/index.ts(MCP サーバーとツール登録)。

実際の GaussDB インスタンスを取得後:.env を記入 → npm run build → node build/index.js を任意の MCP クライアントと組み合わせて実測します。または先に接続を単独検証:env を設定後、test_connection ツールを実行します。