Couchbase

Couchbase MCP Server est un serveur MCP auto-hébergé qui permet aux agents IA de se connecter et d'interagir avec les données dans les clusters Couchbase, qu'ils soient hébergés sur Capella ou auto-gérés. Il fournit des outils dans plusieurs catégories, notamment Cluster Health, Data Schema, Key-Value, Query et Performance — avec des contrôles de sécurité via le mode lecture seule et la désactivation fine des outils. Il prend en charge les transports STDIO et HTTP Streamable.

Couchbase MCP server est distribué sous forme de paquet Python Package Index (PyPI) et via Docker. Le support Entreprise pour Couchbase MCP Server est disponible en concédant la licence Couchbase AI Data Plane, qui donne également droit à l'utilisation et au support Entreprise de Couchbase Agent Memory et Couchbase Agent Catalog.

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

Fonctionnalités/Outils

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 d'analyse des performances des requêtes

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 Capella avec son offre gratuite, qui est une version entièrement gérée du serveur Couchbase. Vous pouvez suivre les instructions pour importer l'un des ensembles 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édéfini, soit à partir du code source en utilisant uv.

Exécution depuis PyPI

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

Configuration du serveur à l'aide du paquet prédéfini 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 le code source

Le serveur MCP peut être exécuté à partir du code source en utilisant ce dépôt.

Clonez le dépôt sur votre machine locale

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

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

Ceci est 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 du 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 (par défaut) : Toutes les opérations d'écriture (KV, Query, gestion des scopes/collections et gestion des index) sont désactivées. Les outils d'écriture KV (upsert, insert, replace, delete, mutation de sous-document), les outils d'écriture de gestion des scopes/collections (create_scope, create_collection, delete_scope, delete_collection) et les outils d'écriture d'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 : Les outils d'écriture KV, de gestion des scopes/collections et d'index sont chargés et les requêtes SQL++ de modification de données/structure sont autorisées.

C'est le défaut sûr recommandé pour éviter les modifications involontaires de données par les LLM.

Note : Pour l'authentification, vous avez besoin soit du nom d'utilisateur et du mot de passe, soit du certificat client et des chemins de clé. Vous pouvez éventuellement spécifier le chemin du certificat racine de l'AC qui sera utilisé pour valider les certificats du serveur. Si le chemin du certificat client & clé et le nom d'utilisateur et le mot de passe sont tous deux 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 peuvent 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 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"
      }
    }
  }
}

Note de sécurité importante

Avertissement : Désactiver des outils ne garantit pas à lui seul que certaines opérations ne peuvent pas être effectuées. Les permissions RBAC (contrôle d'accès basé sur les rôles) de l'utilisateur de base de données sous-jacent sont 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 en utilisant les instructions DML SQL++ (INSERT, UPDATE, DELETE, MERGE) sauf si :

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

Meilleure pratique : Configurez toujours des permissions 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é.

Élicitation/Confirmation pour les appels d'outils

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

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 l'élicitation, l'utilisateur est invité à confirmer.
• Si le client ne prend pas en charge l'élicitation, l'outil s'exécute sans confirmation pour la rétrocompatibilité.

Vous pouvez également vérifier la version du serveur en utilisant :

uvx couchbase-mcp-server --version

Journalisation

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

• CB_MCP_LOG_LEVEL — combien est journalisé : info (le défaut) journalise les événements de 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 (le 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 tourne. Remplacez les niveaux individuels avec CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB (ERROR/WARNING/INFO/DEBUG), également en Mo, qui héritent du global lorsqu'ils ne sont pas définis. Une taille de 0 (globale ou par niveau) est invalide et revient au défaut (1 Mo) avec un avertissement au démarrage. CB_MCP_LOG_MAX_BYTES (octets) est obsolète mais toujours honoré pour la rétrocompatibilité ; 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 combien de sauvegardes de rotation sont conservées par niveau (hors fichier actif) ; le 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'ils ne sont pas définis. Définissez un compte à 0 pour conserver uniquement le fichier actif pour ce niveau — il est toujours plafonné par la taille de rotation (réinitialisé au roulement plutôt que sauvegardé).
• Instantané de configuration du serveur — lorsque le sink file est actif, un enregistrement unique (système d'exploitation, Python, versions de 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 dispose toujours de 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, voir la documentation.

Configuration spécifique au client

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 d'essayer 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 n'émet 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 la Configuration supplémentaire :

• OAuth ne s'active que lorsque les trois **CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER et CB_MCP_OAUTH_JWT_AUDIENCE sont définies ; si seulement certaines sont définies, le démarrage échoue.
• 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). Un accès complet nécessite les deux. Si votre IdP ne peut pas émettre ces étiquettes canoniques, remplacez-les par 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 tous les détails, consultez la documentation.

Image Docker

Le serveur MCP peut également être construit et exécuté comme un conteneur Docker. Des images pré-construites sont disponibles sur DockerHub ou peuvent être récupérées via docker pull docker.io/couchbase/mcp-server:latest.

Alternativement, nous faisons partie du Catalogue MCP Docker.

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 s'appliquent que dans le cas des 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"
      ]
    }
  }
}

Notes

• La valeur de 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, reportez-vous à la documentation Docker.
• Vous pouvez spécifier le réseau du conteneur à l'aide de l'option --network=<your_network>. Le réseau choisi dépend de votre environnement ; la valeur par défaut est bridge. Pour plus de détails, reportez-vous aux 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 la possibilité de sorties inexactes ou nuisibles.
• Couchbase n'examine ni n'évalue la qualité ou l'exactitude de ces sorties, et ces sorties peuvent ne pas refléter les opinions de Couchbase.
• Vous êtes seul responsable de la décision d'utiliser les grands modèles de langage et les technologies connexes, et de vous conformer à toutes conditions de licence, conditions d'utilisation et politiques de votre organisation régissant leur utilisation.

Collecte des 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, les « 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 ni ne collectons les données que vous stockez dans les produits Couchbase. 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 façon dont Couchbase collecte, protège et traite les informations, veuillez vous référer à la politique de confidentialité de Couchbase consultable à l'adresse https://www.couchbase.com/privacy-policy.

Conseils de dépannage

• Assurez-vous que le chemin vers votre dépôt de serveur MCP est correct dans la configuration si vous exécutez depuis la source.
• Vérifiez que votre chaîne de connexion Couchbase, le nom d'utilisateur de la base de données, le 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 est exécuté.
• 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 paquets 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 depuis la source après avoir mis à jour votre dépôt local de serveur MCP, 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
   • Optionnel : CB_MCP_TEST_BUCKET (un bucket à sonder pendant les tests)
2. Exécutez les tests :

uv run pytest tests/ -v

👩‍💻 Contribuer

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

Si vous avez besoin d'aide, avez trouvé un bogue ou souhaitez contribuer à 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, notamment :

• Configuration de l'environnement de développement avec uv
• Linting et formatage du code avec Ruff
• Installation des hooks pre-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 essaieront de résoudre les problèmes au mieux de leurs capacités.

Notre portail de support ne peut pas aider avec les demandes liées à ce projet, nous vous demandons donc de bien vouloir garder toutes les demandes dans GitHub.

Votre collaboration nous aide tous à avancer ensemble — merci !