Add support for mTLS & certificates (#51)

* Add support for mTLS & certificates

- Added support for Basic Authentication and mTLS in the README.md, detailing the required environment variables and configuration examples.
- Updated the `mcp_server.py` to include new command-line options for CA certificate and client certificate paths.
- Modified connection logic in `connection.py` to support mTLS authentication using client certificates, with appropriate error handling for missing files.
- Updated context management in `context.py` to include new certificate paths in the connection setup.
- Enhanced server status reporting in `server.py` to reflect the new authentication configurations.

* Add support for key in CLI arguments

- Revised README.md to add updated environment variable descriptions for mTLS authentication, including the addition of `CB_CLIENT_KEY_PATH`.
- Enhanced `mcp_server.py` to include a new command-line option for the client key path.
- Updated connection logic in `connection.py` to support both client certificate and key paths for mTLS authentication, with improved error handling for missing files.
- Modified context management in `context.py` to incorporate the new client key path in the connection setup.
- Improved server status reporting in `server.py` to reflect the new authentication configurations.

* Update README.md (#52)

* Update README.md

Removed CA_SERVER_CERT from the config examples as it is optional. Also updated "uv" example to indicate path to uv binary

* Update README.md to clarify configuration and troubleshooting instructions

- Simplified the command path for the `uv` binary in the configuration example.
- Corrected the wording in the environment variable table for `CB_CLIENT_KEY_PATH` to clarify its requirement for mTLS.
- Enhanced troubleshooting tips to specify the need for valid database credentials and permissions for at least one bucket.

* Clarify README.md environment variable requirements for mTLS authentication

- Updated the description for `CB_CLIENT_KEY_PATH` in the environment variable table to emphasize the requirement for mTLS authentication, ensuring consistency in the documentation.

---------

Co-authored-by: Nithish Raghunandanan <12782505+nithishr@users.noreply.github.com>

---------

Co-authored-by: Priya Rajagopal <rajagp@users.noreply.github.com>

Author: nithishr

README.md

@@ -32,14 +32,16 @@ An [MCP](https://modelcontextprotocol.io/) server implementation of Couchbase th
 
 ## Configuration
 
-The MCP server can be run either from the pre built PyPI package or the source using uv.
+The MCP server can be run either from the prebuilt PyPI package or the source using uv.
 
 ### Running from PyPI
 
 We publish a pre built [PyPI package](https://pypi.org/project/couchbase-mcp-server/) for the MCP server.
 
 #### Server Configuration using Pre built Package for MCP Clients
 
+#### Basic Authentication
+
 ```json
 {
   "mcpServers": {
@@ -56,6 +58,26 @@ We publish a pre built [PyPI package](https://pypi.org/project/couchbase-mcp-ser
 }
 ```
 
+or
+
+#### mTLS
+
+```json
+{
+  "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"
+      }
+    }
+  }
+}
+```
+
 > Note: If you have other MCP servers in use in the client, you can add it to the existing `mcpServers` object.
 
 ### Running from Source
@@ -100,16 +122,21 @@ This is the common configuration for the MCP clients such as Claude Desktop, Cur
 ### Additional Configuration for MCP Server
 
 The server can be configured using environment variables or command line arguments:
-
-| Environment Variable          | CLI Argument             | Description                                | Default      |
-| ----------------------------- | ------------------------ | ------------------------------------------ | ------------ |
-| `CB_CONNECTION_STRING`        | `--connection-string`    | Connection string to the Couchbase cluster | **Required** |
-| `CB_USERNAME`                 | `--username`             | Username with access to required buckets   | **Required** |
-| `CB_PASSWORD`                 | `--password`             | Password for authentication                | **Required** |
-| `CB_MCP_READ_ONLY_QUERY_MODE` | `--read-only-query-mode` | Prevent data modification queries          | `true`       |
-| `CB_MCP_TRANSPORT`            | `--transport`            | Transport mode: `stdio`, `http`, `sse`     | `stdio`      |
-| `CB_MCP_HOST`                 | `--host`                 | Host for HTTP/SSE transport modes          | `127.0.0.1`  |
-| `CB_MCP_PORT`                 | `--port`                 | Port for HTTP/SSE transport modes          | `8000`       |
+| Environment Variable | CLI Argument | Description | Default |
+|--------------------------------|--------------------------|---------------------------------------------------------------------------------------------|------------------------------------------|
+| `CB_CONNECTION_STRING` | `--connection-string` | Connection string to the Couchbase cluster | **Required** |
+| `CB_USERNAME` | `--username` | Username with access to required buckets for basic authentication | **Required (or Client Certificate and Key needed for mTLS)** |
+| `CB_PASSWORD` | `--password` | Password for basic authentication | **Required (or Client Certificate and Key needed for mTLS)** |
+| `CB_CLIENT_CERT_PATH` | `--client-cert-path` | Path to the client certificate file for mTLS authentication| **Required if using mTLS (or Username and Password required)** |
+| `CB_CLIENT_KEY_PATH` | `--client-key-path` | Path to the client key file for mTLS authentication| **Required if using mTLS (or Username and Password required)** |
+| `CB_CA_CERT_PATH` | `--ca-cert-path` | Path to server root certificate for TLS if server is configured with a self-signed/untrusted certificate. This will not be required if you are connecting to Capella | |
+| `CB_MCP_READ_ONLY_QUERY_MODE` | `--read-only-query-mode` | Prevent data modification queries | `true` |
+| `CB_MCP_TRANSPORT` | `--transport` | Transport mode: `stdio`, `http`, `sse` | `stdio` |
+| `CB_MCP_HOST` | `--host` | Host for HTTP/SSE transport modes | `127.0.0.1` |
+| `CB_MCP_PORT` | `--port` | Port for HTTP/SSE transport modes | `8000` |
+
+> Note: For authentication, you need either the Username and Password or the Client Certificate and key paths. Optionally, you can specify the CA root certificate path that will be used to validate the server certificates.
+> If both the Client Certificate & key path and the username and password are specified, the client certificates will be used for authentication.
 
 You can also check the version of the server using:
 
@@ -370,9 +397,9 @@ The Couchbase MCP server can also be used as a managed server in your agentic ap
 ## Troubleshooting Tips
 
 - Ensure the path to your MCP server repository is correct in the configuration if running from source.
-- Verify that your Couchbase connection string, database username, password are correct.
+- Verify that your Couchbase connection string, database username, password or the path to the certificates are correct.
 - If using Couchbase Capella, ensure that the cluster is [accessible](https://docs.couchbase.com/cloud/clusters/allow-ip-address.html) from the machine where the MCP server is running.
-- Check that the database user has proper permissions to access the specified bucket.
+- Check that the database user has proper permissions to access at least one bucket.
 - Confirm that the `uv` package manager is properly installed and accessible. You may need to provide absolute path to `uv`/`uvx` in the `command` field in the configuration.
 - Check the logs for any errors or warnings that may indicate issues with the MCP server. The location of the logs depend on your MCP client.
 - If you are observing issues running your MCP server from source after updating your local MCP server repository, try running `uv sync` to update the [dependencies](https://docs.astral.sh/uv/concepts/projects/sync/#syncing-the-environment).

src/mcp_server.py

@@ -77,6 +77,24 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
     envvar="CB_PASSWORD",
     help="Couchbase database password (required for operations)",
 )
+@click.option(
+    "--ca-cert-path",
+    envvar="CB_CA_CERT_PATH",
+    default=None,
+    help="Path to the server trust store (CA certificate) file. The certificate at this path is used to verify the server certificate during the authentication process.",
+)
+@click.option(
+    "--client-cert-path",
+    envvar="CB_CLIENT_CERT_PATH",
+    default=None,
+    help="Path to the client certificate file used for mTLS authentication.",
+)
+@click.option(
+    "--client-key-path",
+    envvar="CB_CLIENT_KEY_PATH",
+    default=None,
+    help="Path to the client certificate key file used for mTLS authentication.",
+)
 @click.option(
     "--read-only-query-mode",
     envvar=[
@@ -116,6 +134,9 @@ def main(
     connection_string,
     username,
     password,
+    ca_cert_path,
+    client_cert_path,
+    client_key_path,
     read_only_query_mode,
     transport,
     host,
@@ -127,6 +148,9 @@ def main(
         "connection_string": connection_string,
         "username": username,
         "password": password,
+        "ca_cert_path": ca_cert_path,
+        "client_cert_path": client_cert_path,
+        "client_key_path": client_key_path,
         "read_only_query_mode": read_only_query_mode,
         "transport": transport,
         "host": host,

src/tools/server.py

@@ -30,6 +30,9 @@ def get_server_configuration_status(ctx: Context) -> dict[str, Any]:
         "username": settings.get("username", "Not set"),
         "read_only_query_mode": settings.get("read_only_query_mode", True),
         "password_configured": bool(settings.get("password")),
+        "ca_cert_path_configured": bool(settings.get("ca_cert_path")),
+        "client_cert_path_configured": bool(settings.get("client_cert_path")),
+        "client_key_path_configured": bool(settings.get("client_key_path")),
     }
 
     app_context = ctx.request_context.lifespan_context

src/utils/connection.py

@@ -1,7 +1,8 @@
 import logging
+import os
 from datetime import timedelta
 
-from couchbase.auth import PasswordAuthenticator
+from couchbase.auth import CertificateAuthenticator, PasswordAuthenticator
 from couchbase.cluster import Bucket, Cluster
 from couchbase.options import ClusterOptions
 
@@ -11,15 +12,40 @@
 
 
 def connect_to_couchbase_cluster(
-    connection_string: str, username: str, password: str
+    connection_string: str,
+    username: str,
+    password: str,
+    ca_cert_path: str | None = None,
+    client_cert_path: str | None = None,
+    client_key_path: str | None = None,
 ) -> Cluster:
     """Connect to Couchbase cluster and return the cluster object if successful.
+    The connection can be established using the client certificate and key or the username and password. Optionally, the CA root certificate path can also be provided.
+    Either of the path to the client certificate and key or the username and password should be provided.
+    If the client certificate and key are provided, the username and password are not used.
+    If both the client certificate and key and the username and password are provided, the client certificate is used for authentication.
     If the connection fails, it will raise an exception.
     """
 
     try:
         logger.info("Connecting to Couchbase cluster...")
-        auth = PasswordAuthenticator(username, password)
+        if client_cert_path and client_key_path:
+            logger.info("Connecting to Couchbase cluster with client certificate...")
+            if not os.path.exists(client_cert_path) or not os.path.exists(
+                client_key_path
+            ):
+                raise FileNotFoundError(
+                    f"Client certificate files not found at {os.path.basename(client_cert_path)} or {os.path.basename(client_key_path)}."
+                )
+
+            auth = CertificateAuthenticator(
+                cert_path=client_cert_path,
+                key_path=client_key_path,
+                trust_store_path=ca_cert_path,
+            )
+        else:
+            logger.info("Connecting to Couchbase cluster with password...")
+            auth = PasswordAuthenticator(username, password, cert_path=ca_cert_path)
         options = ClusterOptions(auth)
         options.apply_profile("wan_development")
 

src/utils/context.py

@@ -29,15 +29,27 @@ def _set_cluster_in_lifespan_context(ctx: Context) -> None:
         connection_string = settings.get("connection_string")
         username = settings.get("username")
         password = settings.get("password")
+        ca_cert_path = settings.get("ca_cert_path")
+        client_cert_path = settings.get("client_cert_path")
+        client_key_path = settings.get("client_key_path")
+
         cluster = connect_to_couchbase_cluster(
             connection_string,  # type: ignore
             username,  # type: ignore
             password,  # type: ignore
+            ca_cert_path,
+            client_cert_path,
+            client_key_path,
         )
         ctx.request_context.lifespan_context.cluster = cluster
     except Exception as e:
         logger.error(
-            f"Failed to connect to Couchbase: {e} \n Please check your connection string, username and password"
+            "Failed to connect to Couchbase: %s\n"
+            "Verify connection string, and either:\n"
+            "- Username/password are correct, or\n"
+            "- Client certificate and key exist and match server mapping.\n"
+            "If using self-signed or custom CA, set CB_CA_CERT_PATH to the CA file.",
+            e,
         )
         raise