Couchbase

Serveur MCP Couchbase

Le serveur MCP Couchbase est un serveur Model Context Protocol (MCP) auto-hébergé qui connecte des agents IA et des assistants propulsés par LLM — Claude, Cursor, Windsurf, VS Code Copilot et d'autres clients MCP — aux données des clusters Couchbase, qu'ils soient hébergés sur Capella ou auto-gérés. MCP est un standard ouvert permettant aux assistants IA d'appeler des outils et d'interroger des sources de données externes ; ce serveur implémente ce standard pour Couchbase, afin qu'un agent IA puisse inspecter votre cluster, exécuter des requêtes SQL++, lire et écrire des documents, et analyser les performances des requêtes en langage naturel au lieu de code écrit à la main.

Il fournit des outils répartis dans des catégories incluant la Santé du Cluster, le Schéma de Données, les Opérations Clé-Valeur, les Requêtes et les Performances — avec des contrôles de sécurité via le mode lecture seule (activé par défaut) et la désactivation fine des outils, afin de laisser un agent IA explorer et interroger vos données sans risquer d'écritures non intentionnelles. Il prend en charge les transports STDIO et HTTP Streamable.

Le serveur MCP Couchbase est distribué sous forme de paquet Python Package Index (PyPI) et via Docker. Le support entreprise pour le serveur MCP Couchbase est disponible via la licence Couchbase AI Data Plane, qui inclut également l'utilisation et le support entreprise de Couchbase Agent Memory et Couchbase Agent Catalog.

Pour la documentation complète, visitez mcp-server.couchbase.com.

Pour la documentation complète, visitez docs.couchbase.com/mcp-server.

Table des matières

• Pourquoi le serveur MCP Couchbase
• Exemples de prompts
• Fonctionnalités/Outils
• Prérequis
• Configuration
• Serveur Operational Insights
• Mode de transport HTTP Streamable
• Mode de transport SSE
• Autorisation OAuth 2.1
• Image Docker
• Collecte de données d'utilisation
• Conseils de dépannage
• Tests d'intégration
• FAQ
• Contribution
• Politique de support

Pourquoi le serveur MCP Couchbase

• Sûr par défaut — les opérations d'écriture (upserts/insertions/suppressions de documents et requêtes SQL++ modifiant les données) sont bloquées sauf si vous définissez explicitement CB_MCP_READ_ONLY_MODE=false, et des outils individuels peuvent être désactivés ou soumis à confirmation de l'utilisateur.
• Fonctionne avec Capella et les clusters auto-gérés — la même configuration se connecte à Couchbase Capella (entièrement géré) ou à un cluster Couchbase Server auto-hébergé.
• Sensible au RBAC — la désactivation d'outils est une couche de commodité pour guider le comportement du LLM ; le contrôle d'accès basé sur les rôles de l'utilisateur Couchbase sous-jacent reste la frontière de sécurité faisant autorité.
• Transports de production — exécution via STDIO pour les clients de bureau locaux, ou HTTP Streamable avec OAuth 2.1 optionnel (JWT/JWKS, indépendant du fournisseur — Auth0, Okta, Keycloak, Entra, Cognito, etc.) pour les déploiements partagés/à distance.
• N'importe quel client MCP — testé avec Claude Desktop, Cursor, Windsurf, VS Code et JetBrains AI Assistant/Junie ; fonctionne avec tout client implémentant la spécification MCP.

Exemples de prompts

Une fois le serveur connecté, vous pouvez parler à votre cluster Couchbase en langage naturel via votre assistant IA. Par exemple :

• « Quels buckets, scopes et collections ai-je dans ce cluster, et quel est le schéma de la collection orders ? »
• « Exécutez une requête SQL++ pour trouver les 10 documents les plus récents dans la collection users where status = 'active'. »
• « Quelles sont les 5 requêtes les plus lentes sur ce cluster au cours de la dernière heure, et certaines manquent-elles d'un index couvrant ? »
• « Vérifiez si ce cluster est sain et dites-moi quels services sont en cours d'exécution. »
• « Insérez un nouveau document dans la collection products avec ces champs : ... » (nécessite CB_MCP_READ_ONLY_MODE=false)

Fonctionnalités/Outils

Cette distribution fournit deux serveurs : le serveur opérationnel (par défaut — les tableaux immédiatement ci-dessous) communique avec un cluster Couchbase classique via le SDK couchbase, et le serveur Operational Insights (son propre tableau plus bas) communique avec les clusters Operational Insights via le SDK couchbase-operational-insights.

Outils de configuration et de santé du cluster

Outils de découverte du modèle de données et du schéma

Outils d'opérations KV sur documents

Outils de requête et d'indexation

Outils de recherche en texte intégral (FTS)

Nécessite Couchbase Server 7.6+ et le service Search. La recherche vectorielle n'est pas prise en charge par ces outils (voir les outils de recherche vectorielle séparés).

Outils d'analyse des performances des requêtes

Outils Operational Insights

Enregistrés par le serveur operational-insights séparé (voir Serveur Operational Insights ci-dessous), et non par le serveur operational par défaut.

Les outils de l'API de requêtes asynchrones du serveur forment un flux démarrer → interroger → jeter ou annuler pour les requêtes de longue durée : run_query_async retourne un query_handle, get_async_query_results est interrogé jusqu'à ce qu'il signale la disponibilité (et retourne les lignes), puis soit discard_async_query_results libère les résultats, soit, pour une requête encore en cours, cancel_async_query l'arrête.

Remarque : get_collections_in_scope, get_schema_for_collection, create_index et list_indexes existent, avec un comportement différent, sur les deux serveurs. (get_server_configuration_status apparaît également sur les deux, mais il s'agit délibérément d'un outil partagé — même implémentation, même forme de résultat — il n'a donc pas besoin de désambiguïsation.) Chaque serveur est un processus séparé, donc cela ne pose problème que si un seul client MCP enregistre à la fois operational et operational-insights simultanément — dans ce cas, désambiguïser au niveau de la configuration du client (par exemple en donnant aux deux entrées de serveur des noms distincts dans la configuration du client).

Prérequis

• Python 3.10 ou supérieur.
• Un cluster Couchbase en cours d'exécution. Le moyen le plus simple de commencer est d'utiliser le niveau gratuit Capella, qui est une version entièrement gérée du serveur Couchbase. Vous pouvez suivre les instructions pour importer l'un des jeux de données d'exemple ou importer les vôtres.
• uv installé pour exécuter le serveur.
• Un client MCP tel que Claude Desktop installé pour connecter le serveur à Claude. Les instructions sont fournies pour Claude Desktop et Cursor. D'autres clients MCP peuvent également être utilisés.

Configuration

Le serveur MCP peut être exécuté soit à partir du paquet PyPI précompilé, soit à partir de la source avec uv.

Exécution depuis PyPI

Nous publions un paquet PyPI précompilé pour le serveur MCP.

Configuration du serveur à l'aide du paquet précompilé pour les clients MCP

Authentification de base

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

ou

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

Remarque : Si vous utilisez d'autres serveurs MCP dans le client, vous pouvez l'ajouter à l'objet mcpServers existant.

Exécution depuis la source

Le serveur MCP peut être exécuté depuis la source à l'aide de ce dépôt.

Cloner le dépôt sur votre machine locale

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

Configuration du serveur à l'aide de la source pour les clients MCP

Il s'agit de la configuration courante pour les clients MCP tels que 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"
      }
    }
  }
}

Remarque : path/to/cloned/repo/mcp-server-couchbase/ doit être le chemin vers le dépôt cloné sur votre machine locale. N'oubliez pas la barre oblique finale à la fin !

Remarque : Si vous utilisez d'autres serveurs MCP dans le client, vous pouvez l'ajouter à l'objet mcpServers existant.

Configuration supplémentaire pour le serveur MCP

Le serveur peut être configuré à l'aide de variables d'environnement ou d'arguments de ligne de commande :

Configuration du mode lecture seule

CB_MCP_READ_ONLY_MODE est l'interrupteur unique contrôlant les opérations d'écriture :

• Lorsque true (défaut) : Toutes les opérations d'écriture (KV, Query, gestion des scopes/collections et gestion des index) sont désactivées. Tous les outils d'écriture (KV : upsert, insert, replace, delete, mutation de sous-document ; gestion des scopes/collections : create_scope, create_collection, delete_scope, delete_collection ; gestion des index : create_index, build_index, drop_index) ne sont pas chargés et ne seront pas disponibles pour le LLM, et les requêtes SQL++ qui modifient des données ou la structure sont bloquées.
• Lorsque false : Tous les outils d'écriture sont chargés et les requêtes SQL++ de modification de données/structure sont autorisées.

Il s'agit du défaut sûr recommandé pour éviter les modifications de données involontaires par les LLM.

Remarque : Pour l'authentification, vous avez besoin soit du nom d'utilisateur et du mot de passe, soit des chemins du certificat client et de la clé. En option, vous pouvez spécifier le chemin du certificat racine CA qui sera utilisé pour valider les certificats du serveur. Si à la fois le chemin du certificat client et de la clé et le nom d'utilisateur et le mot de passe sont spécifiés, les certificats clients seront utilisés pour l'authentification.

Désactivation des outils

Vous pouvez désactiver des outils spécifiques pour les empêcher d'être chargés et exposés au client MCP. Les outils désactivés n'apparaîtront pas dans la découverte d'outils et ne pourront pas être invoqués par le LLM.

Formats pris en charge

Liste séparée par des virgules :

# 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

Chemin de fichier (un nom d'outil par ligne) :

# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt

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

Format de fichier (par exemple, disabled_tools.txt) :

# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

Les lignes commençant par # sont traitées comme des commentaires et ignorées.

Exemples de configuration du client MCP

Utilisation d'une liste séparée par des virgules :

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

Utilisation d'un chemin de fichier (recommandé pour de nombreux outils) :

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

Remarque importante sur la sécurité

Avertissement : La désactivation d'outils ne garantit pas à elle seule que certaines opérations ne peuvent pas être effectuées. Les autorisations RBAC (contrôle d'accès basé sur les rôles) de l'utilisateur de la base de données sous-jacente constituent le contrôle de sécurité faisant autorité.

Par exemple, même si vous désactivez upsert_document_by_id et delete_document_by_id, les modifications de données peuvent toujours se produire via l'outil run_sql_plus_plus_query à l'aide d'instructions DML SQL++ (INSERT, UPDATE, DELETE, MERGE) à moins que :

• Le CB_MCP_READ_ONLY_MODE soit défini sur true (par défaut), OU
• L'utilisateur de la base de données ne dispose pas des autorisations RBAC nécessaires pour la modification des données

Meilleure pratique : Configurez toujours des autorisations RBAC appropriées sur vos identifiants utilisateur Couchbase comme mesure de sécurité principale. Utilisez la désactivation d'outils comme couche supplémentaire pour guider le comportement du LLM et réduire la surface d'attaque, et non comme seul contrôle de sécurité.

Sollicitation/Confirmation pour les appels d'outils

Vous pouvez exiger une confirmation explicite de l'utilisateur pour des outils spécifiques avant leur exécution (lorsque le client MCP prend en charge la sollicitation).

CB_MCP_CONFIRMATION_REQUIRED_TOOLS / --confirmation-required-tools prend en charge ces formats :

• Liste séparée par des virgules
• Chemin de fichier (un nom d'outil par ligne, commentaires # pris en charge)

Exemple :

# 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

Lorsqu'un outil répertorié est invoqué :

• Si le client prend en charge la sollicitation, l'utilisateur est invité à confirmer.
• Si le client ne prend pas en charge la sollicitation, l'outil s'exécute sans confirmation pour la compatibilité ascendante.

Vous pouvez également vérifier la version du serveur à l'aide de :

uvx couchbase-mcp-server --version

Journalisation

Le serveur MCP journalise vers stderr par défaut. La journalisation est configurée avec les variables CB_MCP_LOG_* répertoriées dans Configuration supplémentaire :

• CB_MCP_LOG_LEVEL — la quantité journalisée : info (la valeur par défaut) journalise les événements du cycle de vie et les invocations d'outils, debug ajoute des détails internes verbeux, et off désactive toute journalisation.
• CB_MCP_LOG_SINKS — où vont les journaux : stderr (la valeur par défaut), fichiers rotatifs par niveau (file), ou les deux. Avec file, un fichier est écrit par niveau (par exemple mcp_server.info.log et mcp_server.error.log) au chemin défini par CB_MCP_LOG_FILE.
• Taille de rotation — CB_MCP_LOG_ROTATION_MAX_SIZE_MB est la taille globale (en Mo) à laquelle chaque fichier par niveau pivote. Remplacez les niveaux individuels avec CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB (ERROR/WARNING/INFO/DEBUG), également en Mo, qui héritent de la valeur globale lorsqu'elle n'est pas définie. Une taille de 0 (globale ou par niveau) est invalide et revient à la valeur par défaut (1 Mo) avec un avertissement au démarrage. CB_MCP_LOG_MAX_BYTES (octets) est obsolète mais toujours honoré pour la compatibilité ascendante ; il est ignoré lorsque CB_MCP_LOG_ROTATION_MAX_SIZE_MB est également défini, et imprime un avertissement de dépréciation au démarrage.
• Rétention — CB_MCP_LOG_RETENTION_BACKUP_COUNT définit le nombre de sauvegardes rotatives conservées par niveau (hors fichier actif) ; la valeur par défaut de 1 préserve le comportement précédent. Remplacez les niveaux individuels avec CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT (ERROR/WARNING/INFO/DEBUG), qui héritent de la valeur globale lorsqu'elle n'est pas définie. Définissez un nombre à 0 pour ne conserver que le fichier actif pour ce niveau — il est toujours plafonné par la taille de rotation (réinitialisé lors du roulement plutôt que sauvegardé).
• Instantané de configuration du serveur — lorsque le récepteur file est actif, un enregistrement unique (OS, Python, versions des dépendances, transport, configuration de journalisation résolue et configuration serveur expurgée) est écrit en JSON dans un fichier mcp_server_config.log.json dédié (dérivé de la base CB_MCP_LOG_FILE). Il est écrasé à chaque démarrage, donc le support a toujours la configuration actuelle et elle ne sort jamais d'un journal rotatif.

# 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

Pour plus de détails, consultez la documentation.

Configuration spécifique au client

Serveur d'informations opérationnelles

Parallèlement au serveur operational par défaut (celui que chaque section ci-dessus décrit), cette distribution fournit un deuxième serveur pour les clusters Operational Insights, utilisant le SDK séparé couchbase-operational-insights. Il s'agit d'un produit différent d'un cluster Couchbase régulier et il s'exécute comme un processus indépendant sur son propre port.

Exécutez-le en passant operational-insights comme sous-commande CLI (ou en l'ajoutant comme commande du conteneur) :

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 est une URL HTTP(S), pas une chaîne de connexion couchbase:// — par exemple http://localhost:8095 pour un serveur Operational Insights local, ou https://<host>:18095 pour Capella. C'est la mauvaise configuration la plus courante lors du pointage de ce serveur vers un cluster.

Chaque autre indicateur (--read-only-mode, --transport, --host, --port, --disabled-tools, --confirmation-required-tools, --log-*, --oauth-*) est identique à celui du serveur opérationnel — voir Configuration supplémentaire pour le serveur MCP — sauf les valeurs par défaut pour port (8001, pas 8000) et fichier journal (mcp_server_operational_insights.log, pas mcp_server.log), car deux serveurs ne peuvent pas partager l'un ou l'autre. OAuth utilise les mêmes étiquettes de portée (couchbase-mcp:read / couchbase-mcp:write) que le serveur opérationnel, donc une configuration IdP existante fonctionne pour les deux sans modification.

Exemple de configuration de client MCP :

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

Voir Outils Operational Insights ci-dessus pour la liste des outils, et la note concernant les trois noms d'outils partagés avec le serveur opérationnel.

Les deux serveurs partagent une seule entrée Registre MCP, io.github.couchbase/mcp-server-couchbase, publiée depuis server.json. La liste a une entrée de package distincte pour chaque serveur (PyPI et Docker). Chaque entrée transmet sa sous-commande (operational ou operational-insights) et déclare uniquement les arguments et variables d'environnement de ce serveur.

Mode de transport HTTP Streamable

Le serveur MCP peut être exécuté en mode de transport HTTP Streamable, ce qui permet à plusieurs clients de se connecter à la même instance de serveur via HTTP. Vérifiez si votre client MCP prend en charge le transport HTTP streamable avant de tenter de vous connecter au serveur MCP dans ce mode.

Remarque : L'autorisation OAuth 2.1 est prise en charge sur ce transport. Voir Autorisation OAuth 2.1. Sans OAuth configuré, le point de terminaison HTTP n'est pas authentifié.

Utilisation

Par défaut, le serveur MCP s'exécute sur le port 8000, mais cela peut être configuré à l'aide de la variable d'environnement --port ou CB_MCP_PORT.

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

Le serveur sera disponible sur http://localhost:8000/mcp. Cela peut être utilisé dans les clients MCP prenant en charge le mode de transport HTTP streamable, tels que Cursor.

Configuration du client MCP

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

Mode de transport SSE

Il existe une option pour exécuter le serveur MCP en mode de transport Server-Sent Events (SSE).

Remarque : Le mode SSE a été déprécié par MCP. Nous prenons en charge HTTP Streamable.

SSE : Utilisation

Par défaut, le serveur MCP s'exécute sur le port 8000, mais cela peut être configuré à l'aide de la variable d'environnement --port ou CB_MCP_PORT.

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

Le serveur sera disponible sur http://localhost:8000/sse. Cela peut être utilisé dans les clients MCP prenant en charge le mode de transport SSE, tels que Cursor.

SSE : Configuration du client MCP

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

Autorisation OAuth 2.1

Lorsqu'il est exécuté avec --transport=http, le serveur MCP peut agir en tant que serveur de ressources OAuth 2.1 : il valide les JWT porteurs entrants par rapport au JWKS de votre fournisseur d'identité. Il est indépendant du fournisseur (tout fournisseur OAuth 2.1 / OIDC qui publie un JWKS — Auth0, Okta, Keycloak, AWS Cognito, Microsoft Entra, etc.) et ne délivre pas de jetons ni ne gère les utilisateurs. Les paramètres OAuth sont ignorés sur stdio.

OAuth est configuré avec les variables CB_MCP_OAUTH_* répertoriées dans Configuration supplémentaire :

• OAuth s'active uniquement lorsque les trois CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER et CB_MCP_OAUTH_JWT_AUDIENCE sont définis ; n'en définir que certains échoue au démarrage.
• La définition de CB_MCP_OAUTH_MCP_BASE_URL publie en outre les métadonnées de ressource protégée RFC 9728 afin que les clients compatibles PRM puissent découvrir le serveur d'autorisation.
• L'accès est contrôlé par deux portées lues à partir de la revendication scope/scp du jeton : couchbase-mcp:read (outils de lecture, y compris SQL++) et couchbase-mcp:write (outils d'écriture : mutations KV, gestion des portées/collections et gestion des index). L'accès complet nécessite les deux. Si votre IdP ne peut pas émettre ces étiquettes canoniques, remplacez-les avec 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>'

Pour plus de détails, consultez la documentation.

Image Docker

Le serveur MCP peut également être construit et exécuté en tant que conteneur Docker. Des images pré-construites peuvent être trouvées sur DockerHub ou extraites via docker pull docker.io/couchbase/mcp-server:latest.

Alternativement, nous faisons partie du catalogue Docker MCP.

Construction de l'image

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

Exécution

Le serveur MCP peut être exécuté avec les variables d'environnement utilisées pour configurer les paramètres Couchbase. Les variables d'environnement sont les mêmes que celles décrites dans la section Configuration supplémentaire.

Conteneur Docker indépendant

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

Les variables d'environnement CB_MCP_PORT et CB_MCP_HOST ne sont applicables que dans le cas de modes de transport HTTP comme http et sse.

Docker : Configuration du client MCP

L'image Docker peut être utilisée en mode de transport stdio avec la configuration suivante.

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

Remarques

• La valeur couchbase_connection_string dépend du fait que le serveur Couchbase s'exécute sur la même machine hôte, dans un autre conteneur Docker ou sur un hôte distant. Si votre serveur Couchbase s'exécute sur votre machine hôte, votre chaîne de connexion serait probablement de la forme couchbase://host.docker.internal. Pour plus de détails, consultez la documentation docker.
• Vous pouvez spécifier le réseau du conteneur à l'aide de l'option --network=<your_network>. Le réseau que vous choisissez dépend de votre environnement ; la valeur par défaut est bridge. Pour plus de détails, consultez les pilotes réseau dans docker.

Risques associés aux LLM

• L'utilisation de grands modèles de langage et de technologies similaires comporte des risques, notamment le potentiel de sorties inexactes ou nuisibles.
• Couchbase ne révise ni n'évalue la qualité ou l'exactitude de ces sorties, et ces sorties peuvent ne pas refléter les points de vue de Couchbase.
• Vous êtes seul responsable de décider d'utiliser les grands modèles de langage et les technologies connexes, et de vous conformer à toutes les conditions de licence, conditions d'utilisation et politiques de votre organisation régissant votre utilisation de ceux-ci.

Collecte de données d'utilisation

Ce produit collecte automatiquement des données d'utilisation et de performance (telles que le nom et la version du produit) et des informations sur le navigateur (telles que l'adresse IP) (collectivement, « Données d'utilisation »). Couchbase utilise les Données d'utilisation, ainsi que d'autres données que vous pouvez fournir à Couchbase (telles que votre nom d'utilisateur ou votre adresse e-mail), pour développer et améliorer nos produits ainsi que pour informer nos programmes de vente et de marketing. Nous n'accédons pas aux données que vous stockez dans les produits Couchbase et ne les collectons pas. Nous utilisons les Données d'utilisation pour comprendre les modèles d'utilisation agrégés et rendre nos produits plus utiles pour vous. Pour plus d'informations sur la manière dont Couchbase collecte, protège et traite les informations, veuillez consulter la politique de confidentialité Couchbase consultable à https://www.couchbase.com/privacy-policy.

Conseils de dépannage

• Assurez-vous que le chemin vers votre référentiel de serveur MCP est correct dans la configuration si vous l'exécutez à partir de la source.
• Vérifiez que votre chaîne de connexion Couchbase, votre nom d'utilisateur de base de données, votre mot de passe ou le chemin vers les certificats sont corrects.
• Si vous utilisez Couchbase Capella, assurez-vous que le cluster est accessible depuis la machine où le serveur MCP s'exécute.
• Vérifiez que l'utilisateur de la base de données dispose des autorisations appropriées pour accéder à au moins un bucket.
• Confirmez que le gestionnaire de packages uv est correctement installé et accessible. Vous devrez peut-être fournir le chemin absolu vers uv/uvx dans le champ command de la configuration.
• Consultez les journaux pour détecter toute erreur ou avertissement pouvant indiquer des problèmes avec le serveur MCP. L'emplacement des journaux dépend de votre client MCP.
• Si vous rencontrez des problèmes lors de l'exécution de votre serveur MCP à partir de la source après la mise à jour de votre référentiel de serveur MCP local, essayez d'exécuter uv sync pour mettre à jour les dépendances.

Tests d'intégration

Nous fournissons des tests d'intégration MCP de haut niveau pour vérifier que le serveur expose les outils attendus et qu'ils peuvent être invoqués contre un cluster Couchbase de démonstration.

1. Exportez les informations d'identification du cluster de démonstration :
   • CB_CONNECTION_STRING
   • CB_USERNAME
   • CB_PASSWORD
   • Facultatif : CB_MCP_TEST_BUCKET (un bucket à sonder pendant les tests)
   • Facultatif, pour les tests du serveur Operational Insights : CB_OI_CONNECTION_STRING / CB_OI_USERNAME / CB_OI_PASSWORD. Ces tests sont ignorés automatiquement (pas échoués) lorsqu'ils ne sont pas définis.
2. Exécutez les tests :

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

FAQ

Qu'est-ce que le serveur MCP Couchbase ? C'est une implémentation auto-hébergée du Model Context Protocol qui permet aux assistants IA et aux agents (Claude, Cursor, Windsurf, VS Code Copilot, JetBrains AI Assistant/Junie, et tout autre client MCP) d'interroger et, éventuellement, de modifier les données d'un cluster Couchbase en langage naturel.

Comment connecter Claude Desktop à Couchbase ? Installez le serveur avec uvx couchbase-mcp-server (ou exécutez-le à partir de la source ou de Docker), puis ajoutez sa configuration au claude_desktop_config.json de Claude Desktop comme indiqué dans Configuration. Redémarrez Claude Desktop et il détectera les nouveaux outils.

Puis-je utiliser cela avec Couchbase Capella ? Oui. La même configuration CB_CONNECTION_STRING/CB_USERNAME/CB_PASSWORD (ou certificat mTLS) fonctionne pour les clusters Couchbase Capella et Couchbase Server auto-gérés.

Est-il sûr de laisser un agent IA écrire dans ma base de données ? Par défaut, CB_MCP_READ_ONLY_MODE est vrai, donc toutes les opérations d'écriture — upserts/insertions/remplacements/suppressions de documents et instructions SQL++ modifiant les données — sont désactivées et les outils d'écriture ne sont même pas chargés. Vous pouvez également désactiver des outils individuels (voir Désactivation des outils) ou exiger une confirmation explicite de l'utilisateur avant l'exécution d'outils spécifiques (voir Élicitation/Confirmation). Les contrôles au niveau des outils guident le comportement du LLM ; les autorisations RBAC de votre utilisateur Couchbase restent la véritable frontière de sécurité.

Puis-je exécuter des requêtes en langage naturel sur mes données sans écrire moi-même du SQL++ ? Oui — posez une question à votre assistant IA en anglais simple (par exemple « montre-moi les 10 commandes les plus récentes de plus de 100 $ ») et il peut la traduire en une requête SQL++ à l'aide de l'outil run_sql_plus_plus_query. Vous pouvez également demander à l'assistant de explain_sql_plus_plus_query une requête ou demander des recommandations au conseiller d'index. Quelle est la différence entre les transports STDIO, Streamable HTTP et SSE ? STDIO est destiné à un seul client MCP local (par exemple Claude Desktop) qui lance le serveur en tant que sous-processus. Streamable HTTP permet à plusieurs clients de partager une seule instance de serveur en cours d'exécution via HTTP et prend en charge OAuth 2.1. SSE est l'ancien transport HTTP, désormais déprécié par la spécification MCP au profit de Streamable HTTP — voir Mode de transport Streamable HTTP.

Ce projet est-il officiellement pris en charge par Couchbase ? Ce projet est maintenu par la communauté Couchbase — voir Politique de support. Un support entreprise est disponible séparément via Couchbase AI Data Plane.

Contribution

Nous accueillons favorablement les contributions de la communauté ! Que vous souhaitiez corriger des bugs, ajouter des fonctionnalités ou améliorer la documentation, votre aide est appréciée.

Si vous avez besoin d'aide, avez trouvé un bug ou souhaitez proposer des améliorations, le meilleur endroit pour le faire est ici même — en ouvrant un problème GitHub.

Pour les développeurs

Si vous êtes intéressé par la contribution de code ou la mise en place d'un environnement de développement :

📖 Voir CONTRIBUTING.md pour des instructions complètes de configuration pour les développeurs, y compris :

• Configuration de l'environnement de développement avec uv
• Linting et formatage du code avec Ruff
• Installation des hooks de pré-commit
• Aperçu de la structure du projet
• Flux de travail et pratiques de développement

Démarrage rapide pour les contributeurs

# 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

📢 Politique de support

Nous apprécions sincèrement votre intérêt pour ce projet ! Ce projet est maintenu par la communauté Couchbase, ce qui signifie qu'il n'est pas officiellement pris en charge par notre équipe de support. Cependant, nos ingénieurs surveillent et maintiennent activement ce dépôt et s'efforceront de résoudre les problèmes au mieux de leurs capacités.

Notre portail de support ne peut pas traiter les demandes liées à ce projet. Nous vous demandons donc de bien vouloir conserver toutes les demandes dans GitHub.

Votre collaboration nous aide tous à avancer ensemble — merci !