GaussDB MCP

GaussDB-Cloud-Datenbank-MCP-Server von Huawei Cloud. Basierend auf dem offiziellen Huawei GaussDB Node.js-Treiber gaussdb-node, folgt der MCP-Spezifikation 2026-07-28 und bietet 24 Tools und 1 Tabellenstruktur-Ressource für Verbindungstests, Abfragen, Datenschreiben, Transaktionen, Metadaten, Diagnose und Betrieb sowie Benutzerberechtigungen.

Schnellstart

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

Erfordert Node.js ≥ 20.

Related MCP server: mcp-db-assistant

Verbindungskonfiguration

Alle Umgebungsvariablen

Konfiguration für Intranet-Verbindung

Wird verwendet, wenn sich die Anwendung und die GaussDB-Instanz im selben VPC befinden. SSL ist nicht erforderlich (Intranet-Traffic wird nicht nach außen geleitet, Huawei Cloud offiziell standardmäßig Intranet-Direktverbindung):

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

Konfiguration für öffentliche Verbindung

Wird verwendet, wenn die Anwendung nicht im VPC der Instanz liegt und über eine elastische öffentliche IP-Adresse zugegriffen wird. SSL muss aktiviert und ein CA-Zertifikat konfiguriert werden (Huawei Cloud offiziell sslmode=verify-ca-Methode):

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

Vor der öffentlichen Verbindung muss in der Huawei Cloud Konsole in der Sicherheitsgruppe der Zugriff der Client-Ausgangs-IP auf Port 8000 freigegeben werden.

So fügen Sie Umgebungsvariablen hinzu

Zwei Möglichkeiten, wählen Sie eine (wenn beide vorhanden sind, haben Umgebungsvariablen Vorrang vor .env):

1. Projekt-.env-Datei (empfohlen): Kopieren Sie .env.example als .env im Projektstammverzeichnis und füllen Sie es aus. Die Position von .env ist am Projektstammverzeichnis verankert, unabhängig davon, aus welchem Verzeichnis der Server gestartet wird – der MCP-Client kann build/index.js aus jedem Arbeitsverzeichnis starten und es wird gelesen. Die beiden obigen Konfigurationen können direkt in .env geschrieben werden.

2. env-Feld des MCP-Clients: Umgebungsvariablen direkt in der mcpServers-Konfiguration übergeben (siehe Integrationsbeispiel unten), geeignet für Szenarien, in denen keine Anmeldedaten-Dateien im Projekt abgelegt werden sollen.

Bei Haupt-/Standby-Bereitstellung werden mehrere Knoten-IPs in GAUSSDB_HOST mit englischen Kommas getrennt. Der Server versucht beim Start nacheinander zu verbinden und wählt automatisch den ersten verfügbaren Knoten.

Werkzeugübersicht (24)

Alle Werkzeuge sind gemäß MCP-Spezifikation mit Anmerkungen (readOnlyHint/destructiveHint) versehen, sodass der Client bei Schreiboperationen eine Bestätigung anzeigen kann.

Verbindung und Status

Abfrage und Schreiben

Transaktionen (expliziter Handle-Modus)

Verwendung: transaction_begin → mehrere query/execute (mit demselben tx_handle) → transaction_commit oder transaction_rollback.

Metadaten (schreibgeschützt)

Diagnose und Betrieb (nur lesend)

Benutzer und Berechtigungen

Ressourcen

MCP-Client-Integration

Nach dem Build in der Client-Konfigurationsdatei registrieren (am Beispiel des mcpServers-Formats von Claude Desktop / Cursor). Windows verwendet doppelte Backslash-Pfade (E:\\MCP\\GaussDBMCP\\build\\index.js), Linux/macOS verwendet Schrägstriche (/home/user/GaussDBMCP/build/index.js).

Intranet-Verbindung

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

Für die Intranet-Verbindung ist kein SSL erforderlich, keine GAUSSDB_SSL_*-Variablen setzen.

Öffentliche Verbindung

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

Für die öffentliche Verbindung muss SSL aktiviert und ein CA-Zertifikat konfiguriert werden, und die Sicherheitsgruppe muss den Zugriff der Client-Ausgangs-IP auf Port 8000 freigeben.

Alternativ kann env weggelassen werden und die .env-Datei im Projektstammverzeichnis verwendet werden (der Server liest sie beim Start automatisch, verankert am Projektstamm, unabhängig vom Startverzeichnis).

Mehrinstanzen-Isolation (stream = schema)

GAUSSDB_SEARCH_PATH dient gleichzeitig als Schema-Whitelist auf MCP-Ebene: Nach der Konfiguration ist der Zugriff auf das eigene Schema des entsprechenden Streams beschränkt, Tabellen anderer Streams sind nicht sichtbar.

Abfangen auf MCP-Ebene (zuverlässig, basierend auf Strukturparametern):

• list_schemas gibt nur Schemas in der Whitelist zurück, keine anderen Schemanamen werden preisgegeben

• list_tables/list_indexes/list_views/list_sequences standardmäßig auf das erste Whitelist-Schema fixiert, wenn kein Schema übergeben wird, keine Rückgabe aller Datenbanktabellen

• describe_table/insert_rows/update_rows/delete_rows mit explizitem schema-Parameter: Wenn nicht in der Whitelist, wird direkt ein Fehler abgelehnt

• Die Tabellenstruktur-Ressource gaussdb://{schema}/{table}/schema unterliegt ebenfalls der Whitelist, das Lesen über Schemas hinweg wird abgelehnt

Fallback auf Datenbankberechtigungsebene (erforderlich, nicht weglassbar): execute ist beliebiges SQL, die MCP-Ebene führt keine SQL-Analyse durch (handgeschriebene Parser haben immer Umgehungspfade); query erzwingt zwar nur Lesen (Whitelist für erste Schlüsselwörter + Blacklist für Schreibschlüsselwörter + Ablehnung von Mehrfachanweisungen), aber SELECT-förmige Funktionen mit Seiteneffekten (wie pg_terminate_backend, setval) können nicht vollständig abgefangen werden. Zugriff über Schemas hinweg und Seiteneffektfunktionen werden durch GaussDB-Berechtigungen gewährleistet. Jeder Stream verwendet ein separates eingeschränktes Konto, das nur sein eigenes Schema autorisiert:

-- 以管理员执行:为 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 也会被数据库拒绝

Dann in .env GAUSSDB_USER=gycwd_app, GAUSSDB_SEARCH_PATH=gycwd, zwei Ebenen überlagert: Struktureingang MCP-Abfangen, beliebiges SQL Datenbank-Abfangen.

Sicherheitshinweise

• stdio-Serverprotokolle werden alle auf stderr geschrieben, stdout trägt nur MCP-Nachrichten

• Strukturierte Werkzeuge (insert_rows/update_rows/delete_rows usw.) führen Zeichenprüfungen für Tabellennamen/Spaltennamen/Benutzernamen usw. durch, Werte laufen immer über parametrisierte Platzhalter, um SQL-Injection zu verhindern; query/explain_query sind freie SQL-Einstiegspunkte, die durch Nur-Lese-Prüfung und Einzelanweisungsbegrenzung eingeschränkt werden (siehe oben)

• delete_rows/update_rows erzwingen eine where-Bedingung

• explain_query mit analyze=true führt die Anweisung tatsächlich aus, nur SELECT/WITH am Anfang erlaubt und automatisch in Transaktions-Rollback eingebettet (Sequenzfortschritt, Funktionsseiteneffekte können nicht zurückgerollt werden)

• DROP/TRUNCATE-Anweisungen können über execute ausgeführt werden, der Client sollte sich auf die destructiveHint-Annotation verlassen, um eine Bestätigung zu erhalten

• Bitte committen Sie .env nicht in das Versionsverwaltungssystem

Entwicklung und Build

npm run build   # tsc 编译到 build/

Quellcode-Struktur: src/config.ts (Konfiguration), src/db.ts (Verbindungspool und Transaktions-Handles), src/sql.ts (SQL-Konstruktion und Nur-Lese-Prüfung), src/format.ts (Ergebnisformatierung), src/index.ts (MCP-Server und Tool-Registrierung).

Nach Erhalt einer echten GaussDB-Instanz: .env ausfüllen → npm run build → node build/index.js mit einem beliebigen MCP-Client testen; oder zuerst die Verbindung separat verifizieren: Nach Konfiguration der env das Werkzeug test_connection ausführen.