Couchbase

Couchbase MCP Server

Couchbase MCP Server ist ein selbst gehosteter Model Context Protocol (MCP)-Server, der KI-Agenten und LLM-gestützte Assistenten – Claude, Cursor, Windsurf, VS Code Copilot und andere MCP-Clients – mit Daten in Couchbase-Clustern verbindet, egal ob auf Capella gehostet oder selbst verwaltet. MCP ist ein offener Standard, der es KI-Assistenten ermöglicht, Tools aufzurufen und externe Datenquellen abzufragen; dieser Server implementiert diesen Standard für Couchbase, sodass ein KI-Agent Ihren Cluster inspizieren, SQL++-Abfragen ausführen, Dokumente lesen und schreiben und die Abfrageleistung in natürlicher Sprache statt mit handgeschriebenem Code analysieren kann.

Er bietet Tools in Kategorien wie Cluster-Gesundheit, Datenschema, Key-Value, Abfrage und Leistung – mit Sicherheitskontrollen über den Nur-Lese-Modus (standardmäßig aktiviert) und feingranularer Tool-Deaktivierung, sodass Sie einem KI-Agenten erlauben können, Ihre Daten zu erkunden und abzufragen, ohne unbeabsichtigte Schreibvorgänge zu riskieren. Er unterstützt sowohl STDIO- als auch Streamable-HTTP-Transports.

Couchbase MCP Server wird als Python Package Index (PyPI)-Paket und über Docker verteilt. Enterprise-Support für Couchbase MCP Server ist durch die Lizenzierung von Couchbase AI Data Plane verfügbar, die auch die Nutzung und den Enterprise-Support von Couchbase Agent Memory und Couchbase Agent Catalog umfasst.

Für die vollständige Dokumentation besuchen Sie mcp-server.couchbase.com.

Für die vollständige Dokumentation besuchen Sie docs.couchbase.com/mcp-server.

Inhaltsverzeichnis

• Warum Couchbase MCP Server
• Beispiel-Prompts
• Funktionen/Tools
• Voraussetzungen
• Konfiguration
• Operational Insights Server
• Streamable HTTP Transportmodus
• SSE-Transportmodus
• OAuth 2.1-Autorisierung
• Docker-Image
• Nutzungsdatenerfassung
• Tipps zur Fehlerbehebung
• Integrationstests
• FAQ
• Mitwirken
• Support-Richtlinie

Warum Couchbase MCP Server

• Standardmäßig sicher – Schreiboperationen (Dokument-Upserts/Inserts/Deletes und datenmodifizierende SQL++-Abfragen) sind blockiert, es sei denn, Sie setzen explizit CB_MCP_READ_ONLY_MODE=false, und einzelne Tools können deaktiviert oder hinter einer Benutzerbestätigung gesperrt werden.
• Funktioniert mit Capella und selbst verwalteten Clustern – dieselbe Konfiguration verbindet sich mit Couchbase Capella (vollständig verwaltet) oder einem selbst gehosteten Couchbase-Server-Cluster.
• RBAC-bewusst – Die Tool-Deaktivierung ist eine Komfortebene zur Steuerung des LLM-Verhaltens; die rollenbasierte Zugriffskontrolle des zugrunde liegenden Couchbase-Benutzers bleibt die maßgebliche Sicherheitsgrenze.
• Produktionstransporte – Ausführung über STDIO für lokale Desktop-Clients oder Streamable HTTP mit optionaler OAuth 2.1 (JWT/JWKS, anbieterunabhängig – Auth0, Okta, Keycloak, Entra, Cognito usw.) für gemeinsame/Remote-Bereitstellungen.
• Beliebiger MCP-Client – getestet mit Claude Desktop, Cursor, Windsurf, VS Code und JetBrains AI Assistant/Junie; funktioniert mit jedem Client, der die MCP-Spezifikation implementiert.

Beispiel-Prompts

Sobald der Server verbunden ist, können Sie über Ihren KI-Assistenten in natürlicher Sprache mit Ihrem Couchbase-Cluster sprechen. Zum Beispiel:

• „Welche Buckets, Scopes und Collections habe ich in diesem Cluster, und wie ist das Schema der orders-Collection?"
• „Führen Sie eine SQL++-Abfrage aus, um die 10 neuesten Dokumente in der users-Collection where status = 'active' zu finden."
• „Was sind die 5 langsamsten Abfragen auf diesem Cluster in der letzten Stunde, und fehlt einer davon ein abdeckender Index?"
• „Prüfen Sie, ob dieser Cluster gesund ist, und sagen Sie mir, welche Dienste ausgeführt werden."
• „Fügen Sie ein neues Dokument in die products-Collection mit diesen Feldern ein: ..." (erfordert CB_MCP_READ_ONLY_MODE=false)

Funktionen/Tools

Diese Distribution enthält zwei Server: den operationalen Server (Standard – die Tabellen direkt unten) kommuniziert mit einem regulären Couchbase-Cluster über das couchbase SDK, und der Operational Insights- Server (seine eigene Tabelle weiter unten) kommuniziert mit Operational-Insights-Clustern über das couchbase-operational-insights SDK.

Tools für Cluster-Setup und -Gesundheit

Tools zur Datenmodell- und Schema-Erkennung

Tools für Dokument-KV-Operationen

Abfrage- und Indextools

Tools für die Volltextsuche (FTS)

Erfordert Couchbase Server 7.6+ und den Search-Dienst. Die Vektorsuche wird von diesen Tools nicht unterstützt (siehe die separaten Vektorsuch-Tools).

Tools zur Abfrageleistungsanalyse

Operational Insights Tools

Registriert durch den separaten operational-insights-Server (siehe Operational Insights Server unten), nicht durch den Standard-operational-Server.

Die Server-Async-Request-API-Tools bilden einen Ablauf von Start → Abfragen → Verwerfen-oder-Abrechen für langlaufende Abfragen: run_query_async gibt ein query_handle zurück, get_async_query_results wird abgefragt, bis es Bereitschaft meldet (und die Zeilen zurückgibt), dann gibt entweder discard_async_query_results die Ergebnisse frei oder, bei einer noch laufenden Abfrage, stoppt cancel_async_query sie.

Hinweis: get_collections_in_scope, get_schema_for_collection, create_index und list_indexes existieren mit unterschiedlichem Verhalten auf beiden Servern. (get_server_configuration_status erscheint ebenfalls auf beiden, ist aber bewusst ein gemeinsames Tool – gleiche Implementierung, gleiche Ergebnisstruktur – daher ist keine Unterscheidung erforderlich.) Jeder Server ist ein separater Prozess, daher ist dies nur ein Problem, wenn ein einzelner MCP-Client sowohl operational als auch operational-insights gleichzeitig registriert – in diesem Fall unterscheiden Sie auf der Client-Konfigurationsebene (z. B. indem Sie den beiden Servereinträgen in der eigenen Konfiguration des Clients unterschiedliche Namen geben).

Voraussetzungen

• Python 3.10 oder höher.
• Ein laufender Couchbase-Cluster. Der einfachste Einstieg ist die Nutzung des Capella-Kostenlos-Tarifs, der eine vollständig verwaltete Version des Couchbase-Servers ist. Sie können den Anweisungen folgen, um einen der Beispieldatensätze zu importieren oder eigene Daten zu importieren.
• uv installiert, um den Server auszuführen.
• Ein MCP-Client wie Claude Desktop installiert, um den Server mit Claude zu verbinden. Die Anweisungen werden für Claude Desktop und Cursor bereitgestellt. Andere MCP-Clients können ebenfalls verwendet werden.

Konfiguration

Der MCP-Server kann entweder aus dem vorgefertigten PyPI-Paket oder aus dem Quellcode mit uv ausgeführt werden.

Ausführen von PyPI

Wir veröffentlichen ein vorgefertigtes PyPI-Paket für den MCP-Server.

Serverkonfiguration mit vorgefertigtem Paket für MCP-Clients

Basisauthentifizierung

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

oder

mTLS

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
        "CB_CLIENT_KEY_PATH": "/path/to/client.key"
      }
    }
  }
}

Hinweis: Wenn Sie andere MCP-Server im Client verwenden, können Sie ihn zum vorhandenen mcpServers-Objekt hinzufügen.

Ausführen aus dem Quellcode

Der MCP-Server kann aus dem Quellcode mit diesem Repository ausgeführt werden.

Repository auf Ihren lokalen Rechner klonen

git clone https://github.com/couchbase/mcp-server-couchbase.git

Serverkonfiguration mit Quellcode für MCP-Clients

Dies ist die allgemeine Konfiguration für MCP-Clients wie Claude Desktop, Cursor, Windsurf Editor.

{
  "mcpServers": {
    "couchbase": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/mcp-server-couchbase/",
        "run",
        "src/mcp_server.py"
      ],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

Hinweis: path/to/cloned/repo/mcp-server-couchbase/ sollte der Pfad zum geklonten Repository auf Ihrem lokalen Rechner sein. Vergessen Sie nicht den abschließenden Schrägstrich am Ende!

Hinweis: Wenn Sie andere MCP-Server im Client verwenden, können Sie ihn zum vorhandenen mcpServers-Objekt hinzufügen.

Zusätzliche Konfiguration für den MCP-Server

Der Server kann über Umgebungsvariablen oder Befehlszeilenargumente konfiguriert werden:

Konfiguration des Nur-Lese-Modus

CB_MCP_READ_ONLY_MODE ist der einzige Schalter, der Schreiboperationen steuert:

• Wenn true (Standard): Alle Schreiboperationen (KV, Query, Scope/Collection-Verwaltung und Indexverwaltung) sind deaktiviert. Alle Schreib-Tools (KV: upsert, insert, replace, delete, sub-document mutate; Scope/Collection-Verwaltung: create_scope, create_collection, delete_scope, delete_collection; Indexverwaltung: create_index, build_index, drop_index) werden nicht geladen und stehen dem LLM nicht zur Verfügung, und SQL++-Abfragen, die Daten oder Strukturen ändern, werden blockiert.
• Wenn false: Alle Schreib-Tools werden geladen und SQL++-Daten-/Strukturänderungsabfragen sind erlaubt.

Dies ist die empfohlene sichere Standardeinstellung, um unbeabsichtigte Datenänderungen durch LLMs zu verhindern.

Hinweis: Für die Authentifizierung benötigen Sie entweder Benutzername und Passwort oder die Pfade zum Clientzertifikat und -schlüssel. Optional können Sie den Pfad zum CA-Root-Zertifikat angeben, das zur Validierung der Serverzertifikate verwendet wird. Wenn sowohl der Pfad zum Clientzertifikat & -schlüssel als auch Benutzername und Passwort angegeben sind, werden die Clientzertifikate für die Authentifizierung verwendet.

Deaktivieren von Tools

Sie können bestimmte Tools deaktivieren, um zu verhindern, dass sie geladen und dem MCP-Client bereitgestellt werden. Deaktivierte Tools erscheinen nicht in der Tool-Erkennung und können nicht vom LLM aufgerufen werden.

Unterstützte Formate

Kommagetrennte Liste:

# Environment variable
CB_MCP_DISABLED_TOOLS="upsert_document_by_id, delete_document_by_id"

# Command line
uvx couchbase-mcp-server --disabled-tools upsert_document_by_id, delete_document_by_id

Dateipfad (ein Tool-Name pro Zeile):

# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt

# Command line
uvx couchbase-mcp-server --disabled-tools disabled_tools.txt

Dateiformat (z. B. disabled_tools.txt):

# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

Zeilen, die mit # beginnen, werden als Kommentare behandelt und ignoriert.

Beispiele für MCP-Client-Konfiguration

Verwendung einer kommagetrennten Liste:

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_DISABLED_TOOLS": "upsert_document_by_id,delete_document_by_id"
      }
    }
  }
}

Verwendung eines Dateipfads (empfohlen für viele Tools):

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_DISABLED_TOOLS": "/path/to/disabled_tools.txt"
      }
    }
  }
}

Wichtiger Sicherheitshinweis

Warnung: Das alleinige Deaktivieren von Tools garantiert nicht, dass bestimmte Operationen nicht ausgeführt werden können. Die RBAC-Berechtigungen (Role-Based Access Control) des zugrunde liegenden Datenbankbenutzers sind die maßgebliche Sicherheitskontrolle.

Beispielsweise können Datenänderungen auch dann über das Tool run_sql_plus_plus_query mit SQL++-DML-Anweisungen (INSERT, UPDATE, DELETE, MERGE) erfolgen, wenn Sie upsert_document_by_id und delete_document_by_id deaktivieren, es sei denn:

• CB_MCP_READ_ONLY_MODE ist auf true gesetzt (Standard), ODER
• Dem Datenbankbenutzer fehlen die erforderlichen RBAC-Berechtigungen für Datenänderungen

Bewährte Vorgehensweise: Konfigurieren Sie immer geeignete RBAC-Berechtigungen für Ihre Couchbase-Benutzeranmeldeinformationen als primäre Sicherheitsmaßnahme. Verwenden Sie die Tool-Deaktivierung als zusätzliche Ebene, um das LLM-Verhalten zu steuern und die Angriffsfläche zu verringern – nicht als alleinige Sicherheitskontrolle.

Abfrage/Bestätigung für Tool-Aufrufe

Sie können für bestimmte Tools vor der Ausführung eine explizite Benutzerbestätigung verlangen (wenn der MCP-Client Abfragen unterstützt).

CB_MCP_CONFIRMATION_REQUIRED_TOOLS / --confirmation-required-tools unterstützt diese Formate:

• Kommagetrennte Liste
• Dateipfad (ein Tool-Name pro Zeile, #-Kommentare werden unterstützt)

Beispiel:

# Environment variable
CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"

# Command line
uvx couchbase-mcp-server --confirmation-required-tools delete_document_by_id,replace_document_by_id

Wenn ein aufgelistetes Tool aufgerufen wird:

• Wenn der Client Abfragen unterstützt, wird der Benutzer zur Bestätigung aufgefordert.
• Wenn der Client keine Abfragen unterstützt, wird das Tool ohne Bestätigung ausgeführt, um Abwärtskompatibilität zu gewährleisten.

Sie können auch die Version des Servers überprüfen mit:

uvx couchbase-mcp-server --version

Protokollierung

Der MCP-Server protokolliert standardmäßig in stderr. Die Protokollierung wird mit den CB_MCP_LOG_*-Variablen konfiguriert, die in Zusätzliche Konfiguration aufgelistet sind:

• CB_MCP_LOG_LEVEL – wie viel protokolliert wird: info (Standard) protokolliert Lebenszyklusereignisse und Tool-Aufrufe, debug fügt ausführliche interne Details hinzu und off deaktiviert die gesamte Protokollierung.
• CB_MCP_LOG_SINKS – wohin Protokolle gehen: stderr (Standard), rotierende Dateien pro Ebene (file) oder beides. Mit file wird eine Datei pro Ebene geschrieben (z. B. mcp_server.info.log und mcp_server.error.log) unter dem Pfad, der durch CB_MCP_LOG_FILE festgelegt ist.
• Rotationsgröße – CB_MCP_LOG_ROTATION_MAX_SIZE_MB ist die globale Größe (in MB), bei der jede Datei pro Ebene rotiert. Überschreiben Sie einzelne Ebenen mit CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB (ERROR/WARNING/INFO/DEBUG), ebenfalls in MB, die den globalen Wert erben, wenn nicht gesetzt. Eine Größe von 0 (global oder pro Ebene) ist ungültig und fällt mit einer Startwarnung auf den Standardwert (1 MB) zurück. CB_MCP_LOG_MAX_BYTES (Bytes) ist veraltet, wird aber aus Gründen der Abwärtskompatibilität weiterhin berücksichtigt; es wird ignoriert, wenn CB_MCP_LOG_ROTATION_MAX_SIZE_MB ebenfalls gesetzt ist, und gibt beim Start eine Veraltungswarnung aus.
• Aufbewahrung – CB_MCP_LOG_RETENTION_BACKUP_COUNT legt fest, wie viele rotierte Sicherungskopien pro Ebene aufbewahrt werden (ohne die aktive Datei); der Standardwert von 1 bewahrt das bisherige Verhalten. Überschreiben Sie einzelne Ebenen mit CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT (ERROR/WARNING/INFO/DEBUG), die den globalen Wert erben, wenn nicht gesetzt. Setzen Sie eine Anzahl auf 0, um nur die aktive Datei für diese Ebene aufzubewahren – sie ist weiterhin durch die Rotationsgröße begrenzt (wird beim Rollover zurückgesetzt, nicht gesichert).
• Server-Konfigurations-Snapshot – wenn der file-Sink aktiv ist, wird ein einmaliger Datensatz (Betriebssystem, Python, Abhängigkeitsversionen, Transport, aufgelöste Protokollierungskonfiguration und redigierte Serverkonfiguration) als JSON in eine dedizierte mcp_server_config.log.json-Datei geschrieben (abgeleitet von der CB_MCP_LOG_FILE-Basis). Sie wird bei jedem Start überschrieben, sodass der Support immer die aktuelle Konfiguration hat und sie nie aus einem rotierenden Protokoll herausfällt.

# Enable debug logging to both stderr and rotating per-level files
uvx couchbase-mcp-server --log-level=debug --log-sinks=stderr,file

# Keep 30 rotated ERROR backups but only the live DEBUG file
uvx couchbase-mcp-server --log-level=debug --log-sinks=file \
  --log-error-retention-backup-count=30 --log-debug-retention-backup-count=0

Weitere Details finden Sie in der Dokumentation.

Clientspezifische Konfiguration

Operational-Insights-Server

Neben dem Standard-operational-Server (dem Server, den jeder Abschnitt oben beschreibt), enthält diese Distribution einen zweiten Server für Operational Insights-Cluster, der das separate couchbase-operational-insights-SDK verwendet. Es handelt sich um ein anderes Produkt als ein regulärer Couchbase-Cluster, und er läuft als unabhängiger Prozess auf einem eigenen Port.

Führen Sie ihn aus, indem Sie operational-insights als CLI-Unterbefehl übergeben (oder ihn als Befehl des Containers anhängen):

uvx couchbase-mcp-server operational-insights
# or, from source:
uv run src/mcp_server.py operational-insights
# or, via Docker:
docker run --rm -i \
  -e CB_OI_CONNECTION_STRING=http://localhost:8095 \
  -e CB_OI_USERNAME=Administrator \
  -e CB_OI_PASSWORD=password \
  couchbase/mcp-server:<version> operational-insights

--connection-string ist eine HTTP(S)-URL, keine couchbase://-Verbindungszeichenfolge – z. B. http://localhost:8095 für einen lokalen Operational-Insights-Server oder https://<host>:18095 für Capella. Dies ist die häufigste Fehlkonfiguration, wenn dieser Server auf einen Cluster ausgerichtet wird.

Jedes andere Flag (--read-only-mode, --transport, --host, --port, --disabled-tools, --confirmation-required-tools, --log-*, --oauth-*) ist identisch mit dem des operativen Servers – siehe Zusätzliche Konfiguration für den MCP-Server – mit Ausnahme der Standardwerte für Port (8001, nicht 8000) und Logdatei (mcp_server_operational_insights.log, nicht mcp_server.log), da zwei Server sich keines von beidem teilen können. OAuth verwendet dieselben Bereichsbezeichnungen (couchbase-mcp:read / couchbase-mcp:write) wie der operative Server, sodass eine bestehende IdP-Konfiguration ohne Änderungen für beide funktioniert.

Beispielkonfiguration für einen MCP-Client:

{
  "mcpServers": {
    "couchbase-operational-insights": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OI_CONNECTION_STRING": "http://localhost:8095",
        "CB_OI_USERNAME": "Administrator",
        "CB_OI_PASSWORD": "password"
      }
    }
  }
}

Siehe Operational-Insights-Tools oben für die Tool-Liste sowie den Hinweis dort zu den drei Tool-Namen, die mit dem operativen Server geteilt werden.

Beide Server teilen sich einen einzigen MCP-Registry- Eintrag, io.github.couchbase/mcp-server-couchbase, veröffentlicht über server.json. Der Eintrag enthält einen separaten Paketeintrag für jeden Server (PyPI und Docker). Jeder Eintrag übergibt seinen Unterbefehl (operational oder operational-insights) und deklariert nur die Argumente und Umgebungsvariablen dieses Servers.

Streamable-HTTP-Transportmodus

Der MCP-Server kann im Streamable-HTTP-Transportmodus ausgeführt werden, der es mehreren Clients ermöglicht, über HTTP eine Verbindung zur selben Serverinstanz herzustellen. Prüfen Sie, ob Ihr MCP-Client den Streamable-HTTP-Transport unterstützt, bevor Sie versuchen, sich in diesem Modus mit dem MCP-Server zu verbinden.

Hinweis: Die OAuth-2.1-Autorisierung wird bei diesem Transport unterstützt. Siehe OAuth-2.1-Autorisierung. Ohne konfiguriertes OAuth ist der HTTP-Endpunkt nicht authentifiziert.

Verwendung

Standardmäßig läuft der MCP-Server auf Port 8000, dies kann jedoch über die Umgebungsvariable --port oder CB_MCP_PORT konfiguriert werden.

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-mode=true \
  --transport=http

Der Server ist unter http://localhost:8000/mcp verfügbar. Dies kann in MCP-Clients verwendet werden, die den Streamable-HTTP-Transportmodus unterstützen, wie z. B. Cursor.

MCP-Client-Konfiguration

{
  "mcpServers": {
    "couchbase-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

SSE-Transportmodus

Es gibt die Option, den MCP-Server im Server-Sent-Events (SSE)-Transportmodus auszuführen.

Hinweis: Der SSE-Modus wurde von MCP als veraltet eingestuft. Wir unterstützen Streamable HTTP.

SSE: Verwendung

Standardmäßig läuft der MCP-Server auf Port 8000, dies kann jedoch über die Umgebungsvariable --port oder CB_MCP_PORT konfiguriert werden.

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-mode=true \
  --transport=sse

Der Server ist unter http://localhost:8000/sse verfügbar. Dies kann in MCP-Clients verwendet werden, die den SSE-Transportmodus unterstützen, wie z. B. Cursor.

SSE: MCP-Client-Konfiguration

{
  "mcpServers": {
    "couchbase-sse": {
      "url": "http://localhost:8000/sse"
    }
  }
}

OAuth-2.1-Autorisierung

Bei Ausführung mit --transport=http kann der MCP-Server als OAuth-2.1-Ressourcenserver fungieren: Er validiert eingehende Bearer-JWTs gegen die JWKS Ihres Identitätsanbieters. Er ist anbieterunabhängig (jeder OAuth-2.1-/OIDC-Anbieter, der eine JWKS veröffentlicht – Auth0, Okta, Keycloak, AWS Cognito, Microsoft Entra usw.) und stellt keine Token aus und verwaltet keine Benutzer. OAuth-Einstellungen werden bei stdio ignoriert.

OAuth wird mit den CB_MCP_OAUTH_*-Variablen konfiguriert, die in Zusätzliche Konfiguration aufgeführt sind:

• OAuth wird nur aktiviert, wenn alle drei von CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER und CB_MCP_OAUTH_JWT_AUDIENCE gesetzt sind; wenn nur einige davon gesetzt sind, schlägt der Start fehl.
• Das Setzen von CB_MCP_OAUTH_MCP_BASE_URL veröffentlicht zusätzlich RFC-9728-Protected-Resource-Metadaten, sodass PRM-fähige Clients den Autorisierungsserver erkennen können.
• Der Zugriff wird durch zwei Bereiche gesteuert, die aus dem scope/scp-Anspruch des Tokens gelesen werden: couchbase-mcp:read (Lesetools, einschließlich SQL++) und couchbase-mcp:write (Schreibtools: KV-Mutationen, Scope-/Collection-Verwaltung und Indexverwaltung). Für den vollständigen Zugriff sind beide erforderlich. Wenn Ihr IdP diese kanonischen Bezeichnungen nicht ausgeben kann, überschreiben Sie sie mit CB_MCP_OAUTH_SCOPE_READ_LABEL / CB_MCP_OAUTH_SCOPE_WRITE_LABEL.

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --transport=http \
  --oauth-jwks-uri='https://auth.example.com/.well-known/jwks.json' \
  --oauth-issuer='https://auth.example.com/' \
  --oauth-audience='couchbase-mcp-server' \
  --oauth-mcp-base-url='<public_base_url_of_this_server>'

Ausführliche Details finden Sie in der Dokumentation.

Docker-Image

Der MCP-Server kann auch als Docker-Container erstellt und ausgeführt werden. Vorgefertigte Images finden Sie auf DockerHub oder können über docker pull docker.io/couchbase/mcp-server:latest bezogen werden.

Alternativ sind wir Teil des Docker-MCP-Katalogs.

Image erstellen

docker build -t mcp/couchbase-src .

docker build --build-arg GIT_COMMIT_HASH=$(git rev-parse HEAD) \
  --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
  -t mcp/couchbase-src .

# Build with default image name (mcp/couchbase-src)
./build.sh

# Build with custom image name
./build.sh my-custom/image-name

# View git commit hash in image
docker inspect --format='{{index .Config.Labels "org.opencontainers.image.revision"}}' mcp/couchbase-src:latest

# View all metadata labels
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase-src:latest

Ausführen

Der MCP-Server kann mit den Umgebungsvariablen ausgeführt werden, die zur Konfiguration der Couchbase-Einstellungen verwendet werden. Die Umgebungsvariablen sind dieselben wie im Abschnitt „Zusätzliche Konfiguration“ beschrieben.

Unabhängiger Docker-Container

docker run --rm -i \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_MCP_TRANSPORT='<http|sse|stdio>' \
  -e CB_MCP_READ_ONLY_MODE='<true|false>' \
  -e CB_MCP_CONFIRMATION_REQUIRED_TOOLS='delete_document_by_id' \
  -e CB_MCP_PORT=9001 \
  -e CB_MCP_HOST=0.0.0.0 \
  -p 9001:9001 \
  mcp/couchbase-src

Die Umgebungsvariablen CB_MCP_PORT und CB_MCP_HOST gelten nur für HTTP-Transportmodi wie http und sse.

Docker: MCP-Client-Konfiguration

Das Docker-Image kann im stdio-Transportmodus mit der folgenden Konfiguration verwendet werden.

{
  "mcpServers": {
    "couchbase-mcp-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CB_CONNECTION_STRING=<couchbase_connection_string>",
        "-e",
        "CB_USERNAME=<database_user>",
        "-e",
        "CB_PASSWORD=<database_password>",
        "mcp/couchbase-src"
      ]
    }
  }
}

Hinweise

• Der couchbase_connection_string-Wert hängt davon ab, ob der Couchbase-Server auf demselben Host-Rechner, in einem anderen Docker-Container oder auf einem Remote-Host ausgeführt wird. Wenn Ihr Couchbase-Server auf Ihrem Host-Rechner läuft, hat Ihre Verbindungszeichenfolge wahrscheinlich die Form couchbase://host.docker.internal. Details finden Sie in der Docker-Dokumentation.
• Sie können die Netzwerkkonfiguration des Containers über die Option --network=<your_network> festlegen. Das von Ihnen gewählte Netzwerk hängt von Ihrer Umgebung ab; der Standard ist bridge. Details finden Sie unter Netzwerktreiber in Docker.

Risiken im Zusammenhang mit LLMs

• Die Verwendung großer Sprachmodelle und ähnlicher Technologien birgt Risiken, einschließlich der Möglichkeit ungenauer oder schädlicher Ausgaben.
• Couchbase überprüft oder bewertet nicht die Qualität oder Genauigkeit solcher Ausgaben, und solche Ausgaben geben möglicherweise nicht die Ansichten von Couchbase wieder.
• Sie sind allein dafür verantwortlich zu entscheiden, ob Sie große Sprachmodelle und verwandte Technologien verwenden, und alle Lizenzbedingungen, Nutzungsbedingungen und Richtlinien Ihrer Organisation für deren Verwendung einzuhalten.

Erfassung von Nutzungsdaten

Dieses Produkt erfasst automatisch Nutzungs- und Leistungsdaten (wie Produktname und -version) sowie Browserinformationen (wie IP-Adresse) (zusammen „Nutzungsdaten“). Couchbase verwendet Nutzungsdaten zusammen mit anderen Daten, die Sie Couchbase möglicherweise zur Verfügung stellen (wie Ihren Benutzernamen oder Ihre E-Mail-Adresse), um unsere Produkte zu entwickeln und zu verbessern sowie unsere Vertriebs- und Marketingprogramme zu informieren. Wir greifen nicht auf Daten zu, die Sie in Couchbase-Produkten speichern, und sammeln diese auch nicht. Wir verwenden Nutzungsdaten, um aggregierte Nutzungsmuster zu verstehen und unsere Produkte für Sie nützlicher zu machen. Weitere Informationen darüber, wie Couchbase Informationen erfasst, schützt und verarbeitet, finden Sie in der Couchbase-Datenschutzrichtlinie unter https://www.couchbase.com/privacy-policy.

Tipps zur Fehlerbehebung

• Stellen Sie sicher, dass der Pfad zu Ihrem MCP-Server-Repository in der Konfiguration korrekt ist, wenn Sie aus dem Quellcode ausführen.
• Überprüfen Sie, ob Ihre Couchbase-Verbindungszeichenfolge, der Datenbankbenutzername, das Passwort oder der Pfad zu den Zertifikaten korrekt sind.
• Wenn Sie Couchbase Capella verwenden, stellen Sie sicher, dass der Cluster von dem Rechner aus zugänglich ist, auf dem der MCP-Server ausgeführt wird.
• Stellen Sie sicher, dass der Datenbankbenutzer über die entsprechenden Berechtigungen verfügt, um auf mindestens einen Bucket zuzugreifen.
• Bestätigen Sie, dass der Paketmanager uv ordnungsgemäß installiert und zugänglich ist. Möglicherweise müssen Sie den absoluten Pfad zu uv/uvx im Feld command in der Konfiguration angeben.
• Überprüfen Sie die Protokolle auf Fehler oder Warnungen, die auf Probleme mit dem MCP-Server hinweisen könnten. Der Speicherort der Protokolle hängt von Ihrem MCP-Client ab.
• Wenn Sie Probleme bei der Ausführung Ihres MCP-Servers aus dem Quellcode nach der Aktualisierung Ihres lokalen MCP-Server-Repositorys feststellen, versuchen Sie, uv sync auszuführen, um die Abhängigkeiten zu aktualisieren.

Integrationstests

Wir stellen hochrangige MCP-Integrationstests bereit, um zu überprüfen, ob der Server die erwarteten Tools verfügbar macht und ob diese gegen einen Demo-Couchbase-Cluster aufgerufen werden können.

1. Exportieren Sie die Anmeldeinformationen des Demo-Clusters:
   • CB_CONNECTION_STRING
   • CB_USERNAME
   • CB_PASSWORD
   • Optional: CB_MCP_TEST_BUCKET (ein Bucket, der während der Tests untersucht werden soll)
   • Optional, für die eigenen Tests des Operational-Insights-Servers: CB_OI_CONNECTION_STRING / CB_OI_USERNAME / CB_OI_PASSWORD. Diese Tests werden automatisch übersprungen (nicht fehlgeschlagen), wenn sie nicht gesetzt sind.
2. Führen Sie die Tests aus:

uv run --extra dev pytest tests/integration -v

FAQ

Was ist der Couchbase-MCP-Server? Es ist eine selbst gehostete Implementierung des Model Context Protocol, die es KI-Assistenten und -Agenten (Claude, Cursor, Windsurf, VS Code Copilot, JetBrains AI Assistant/Junie und jedem anderen MCP-Client) ermöglicht, Daten in einem Couchbase-Cluster mithilfe natürlicher Sprache abzufragen und optional zu ändern.

Wie verbinde ich Claude Desktop mit Couchbase? Installieren Sie den Server mit uvx couchbase-mcp-server (oder führen Sie ihn aus dem Quellcode oder Docker aus) und fügen Sie dann seine Konfiguration zur claude_desktop_config.json von Claude Desktop hinzu, wie in Konfiguration gezeigt. Starten Sie Claude Desktop neu, und es übernimmt die neuen Tools.

Kann ich dies mit Couchbase Capella verwenden? Ja. Dieselbe CB_CONNECTION_STRING/CB_USERNAME/CB_PASSWORD-Konfiguration (oder das mTLS-Zertifikat) funktioniert sowohl für Couchbase Capella als auch für selbst verwaltete Couchbase-Server-Cluster.

Ist es sicher, einem KI-Agenten das Schreiben in meine Datenbank zu erlauben? Standardmäßig ist CB_MCP_READ_ONLY_MODE true, sodass alle Schreibvorgänge – Dokument-Upserts/Einfügungen/Ersetzungen/Löschungen und datenändernde SQL++-Anweisungen – deaktiviert sind und die Schreib-Tools nicht einmal geladen werden. Sie können auch einzelne Tools deaktivieren (siehe Tools deaktivieren) oder eine explizite Benutzerbestätigung verlangen, bevor bestimmte Tools ausgeführt werden (siehe Elicitation/Bestätigung). Tool-Ebene-Steuerungen leiten das LLM-Verhalten; die RBAC-Berechtigungen Ihres Couchbase-Benutzers bleiben die eigentliche Sicherheitsgrenze.

Kann ich natürliche Sprachabfragen gegen meine Daten ausführen, ohne SQL++ selbst zu schreiben? Ja – stellen Sie Ihrem KI-Assistenten eine Frage in einfachem Englisch (z. B. „zeig mir die 10 neuesten Bestellungen über 100 $“), und er kann dies mithilfe des run_sql_plus_plus_query-Tools in eine SQL++-Abfrage übersetzen. Sie können den Assistenten auch bitten, eine Abfrage zu explain_sql_plus_plus_query oder den Indexberater um Empfehlungen zu bitten. Was ist der Unterschied zwischen STDIO-, Streamable-HTTP- und SSE-Transport? STDIO ist für einen einzelnen lokalen MCP-Client (z. B. Claude Desktop) gedacht, der den Server als Unterprozess startet. Streamable HTTP ermöglicht mehreren Clients, eine gemeinsam genutzte Serverinstanz über HTTP zu verwenden, und unterstützt OAuth 2.1. SSE ist der ältere HTTP-Transport, der von der MCP-Spezifikation zugunsten von Streamable HTTP als veraltet eingestuft wurde – siehe Streamable-HTTP-Transportmodus.

Wird dies offiziell von Couchbase unterstützt? Dieses Projekt wird von der Couchbase-Community gepflegt – siehe Support-Richtlinie. Enterprise-Support ist separat über Couchbase AI Data Plane verfügbar.

Mitwirken

Wir freuen uns über Beiträge aus der Community! Ob Sie Fehler beheben, Funktionen hinzufügen oder die Dokumentation verbessern möchten – Ihre Hilfe ist willkommen.

Wenn Sie Hilfe benötigen, einen Fehler gefunden haben oder Verbesserungen beitragen möchten, ist der beste Ort dafür genau hier – indem Sie ein GitHub-Issue eröffnen.

Für Entwickler

Wenn Sie daran interessiert sind, Code beizutragen oder eine Entwicklungsumgebung einzurichten:

📖 Siehe CONTRIBUTING.md für umfassende Entwickler-Setup-Anweisungen, einschließlich:

• Einrichtung der Entwicklungsumgebung mit uv
• Code-Linting und -Formatierung mit Ruff
• Installation von Pre-Commit-Hooks
• Überblick über die Projektstruktur
• Entwicklungsworkflow und -praktiken

Schnellstart für Mitwirkende

# Clone and setup
git clone https://github.com/couchbase/mcp-server-couchbase.git
cd mcp-server-couchbase

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

# Run linting
./scripts/lint.sh

📢 Support-Richtlinie

Wir schätzen Ihr Interesse an diesem Projekt sehr! Dieses Projekt wird von der Couchbase-Community gepflegt, was bedeutet, dass es nicht offiziell von unserem Support-Team unterstützt wird. Unsere Ingenieure überwachen und pflegen dieses Repository jedoch aktiv und werden sich nach besten Kräften bemühen, Probleme zu lösen.

Unser Support-Portal kann bei Anfragen zu diesem Projekt nicht helfen. Daher bitten wir Sie, alle Anfragen innerhalb von GitHub zu halten.

Ihre Zusammenarbeit hilft uns allen, gemeinsam voranzukommen – vielen Dank!