Couchbase MCP Server

Serveur MCP Couchbase

Le serveur MCP Couchbase est un serveur MCP auto-hébergé qui permet aux agents IA de se connecter et d'interagir avec les données des clusters Couchbase, qu'ils soient hébergés sur Capella ou autogérés. Il fournit des outils couvrant des catégories telles que la santé du cluster, le schéma de données, les paires clé-valeur, les requêtes et les performances — avec des contrôles de sécurité via le mode lecture seule et la désactivation granulaire des outils. Il prend en charge les transports STDIO et HTTP Streamable.

Le serveur MCP Couchbase est distribué sous forme de package Python Package Index (PyPI) et via Docker. Le support entreprise pour le serveur MCP Couchbase est disponible en licenciant Couchbase AI Data Plane, ce qui donne également droit à l'utilisation et au support entreprise de Couchbase Agent Memory et Couchbase Agent Catalog.

Pour la documentation complète, visitez 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 les 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 le niveau gratuit de 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 package PyPI préconstruit, soit à partir des sources en utilisant uv.

Exécution à partir de PyPI

Nous publions un package PyPI préconstruit pour le serveur MCP.

Configuration du serveur en utilisant le package préconstruit 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 avez d'autres serveurs MCP en cours d'utilisation dans le client, vous pouvez l'ajouter à l'objet mcpServers existant.

Exécution à partir des sources

Le serveur MCP peut être exécuté à partir des sources en utilisant 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 en utilisant les sources pour les clients MCP

Ceci est la configuration commune 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 avez d'autres serveurs MCP en cours d'utilisation dans le client, vous pouvez l'ajouter à l'objet mcpServers existant.

Configuration supplémentaire pour le serveur MCP

Le serveur peut être configuré en utilisant des variables d'environnement ou des arguments de ligne de commande :

Configuration du mode lecture seule

CB_MCP_READ_ONLY_MODE est le commutateur unique contrôlant les opérations d'écriture :

• Lorsque true (par défaut) : Toutes les opérations d'écriture (KV et Query) sont désactivées. Les outils d'écriture KV (upsert, insert, replace, delete) ne sont pas chargés et ne seront pas disponibles pour le LLM, et les requêtes SQL++ qui modifient les données ou la structure sont bloquées.
• Lorsque false : Les outils d'écriture KV sont chargés et les requêtes SQL++ de modification de données/structure sont autorisées.

C'est la valeur par défaut sécurisée recommandée pour empêcher 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 du certificat client et des chemins de clé. Optionnellement, vous pouvez spécifier le chemin du certificat racine CA qui sera utilisé pour valider les certificats du serveur. Si le certificat client et le chemin de clé ainsi que 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 empêcher qu'ils soient 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"
      }
    }
  }
}

Note de sécurité importante

Avertissement : La simple désactivation des outils ne garantit pas que certaines opérations ne puissent 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, des modifications de données peuvent toujours se produire via l'outil run_sql_plus_plus_query en utilisant des instructions DML SQL++ (INSERT, UPDATE, DELETE, MERGE), sauf si :

• 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 autorisations RBAC nécessaires pour la modification des données

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

Elicitation/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 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, les commentaires # sont 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 des raisons de compatibilité ascendante.

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

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 — quantité d'informations journalisées : info (par défaut) journalise les événements de cycle de vie et les invocations d'outils, debug ajoute des détails internes détaillés, et off désactive toute journalisation.
• CB_MCP_LOG_SINKS — destination des journaux : stderr (par défaut), fichiers tournants 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.

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

Pour plus de détails, consultez 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 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écutera sur le port 8000, mais cela peut être configuré en utilisant 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 tel 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 le HTTP streamable.

SSE : Utilisation

Par défaut, le serveur MCP s'exécutera sur le port 8000, mais cela peut être configuré en utilisant 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 tel que Cursor.

SSE : Configuration du client MCP

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

Autorisation OAuth 2.1

Lors de l'exécution avec --transport=http, le serveur MCP peut agir comme un 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 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.
• Définir CB_MCP_OAUTH_MCP_BASE_URL publie en plus les métadonnées de ressource protégée RFC 9728 afin que les clients conscients de PRM puissent découvrir le serveur d'autorisation.
• L'accès est contrôlé par deux étendues lues à partir de la revendication scope/scp du jeton : couchbase-mcp:read (outils de lecture, y compris SQL++) et couchbase-mcp:write (outils de mutation KV). L'accès complet nécessite les deux.

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

Remarques

• 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 la mise en 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, 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 résultats inexacts ou nuisibles.
• Couchbase n'examine ni n'évalue la qualité ou l'exactitude de ces résultats, et ces résultats peuvent ne pas refléter les vues de Couchbase.
• Vous êtes seul responsable de déterminer s'il convient d'utiliser de grands modèles de langage et les technologies associées, et de respecter les conditions de licence, les conditions d'utilisation et les politiques de votre organisation régissant leur utilisation.

Conseils de dépannage

• Assurez-vous que le chemin vers votre dépôt de serveur MCP est correct dans la configuration si vous l'exécutez à partir des sources.
• 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 observez des problèmes lors de l'exécution de votre serveur MCP à partir des sources après avoir mis à jour votre dépôt local du 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 sur 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)
2. Exécutez les tests :

uv run pytest tests/ -v

👩‍💻 Contribution

Nous accueillons 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 une issue GitHub.

Pour les développeurs

Si vous souhaitez contribuer au code ou configurer un environnement de développement :

📖 Consultez 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 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 supporté 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 dans la mesure du possible.

Notre portail de support n'est pas en mesure de traiter les demandes liées à ce projet, nous vous demandons donc de bien vouloir adresser toutes vos questions via GitHub.

Votre collaboration nous aide tous à avancer ensemble — merci !