Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Build from Source

    Build and run the Couchbase MCP Server from source, including Docker image builds.

    This page provides a step-by-step guide to building the Couchbase MCP Server from source when you want to run it locally, test the latest changes, or extend it directly from the GitHub repository. It covers cloning the repository, configuring your MCP client, and optionally building a Docker image from source.

    Prerequisites

    • Python 3.10—3.14 installed — the server supports Python versions in security or bug-fix (maintenance) status; End-of-Life versions are not supported.

    • uv installed

    • Git installed

    Clone the Repository

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

    Running the Source Code Directly

    You can run the MCP server directly from the source using uv.

    Source: MCP Client Configuration

    When configuring an MCP client, use this command format:

    {
  "mcpServers": {
    "couchbase": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/mcp-server-couchbase/",
        "run",
        "src/mcp_server.py"
      ],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://your-connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}
    path/to/cloned/repo/mcp-server-couchbase/ should be the absolute path to the cloned repository on your local machine. Do not forget the trailing slash.
    If you have other MCP servers configured, add the couchbase entry to the existing mcpServers object.

    Dockerize from Source

    You can also build and run the server as a Docker container from the cloned repository.

    Build the Image

    docker build -t mcp/couchbase-src .

    To include build metadata (git commit hash and build timestamp):

    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 .

    Or use the provided build script:

    Build with default image name (mcp/couchbase-src)

    ./build.sh

    Build with custom image name

    ./build.sh my-custom/image-name

    The script does the following:

    • Accepts an optional image name parameter (defaults to mcp/couchbase-src)

    • Generates git commit hash and build timestamp

    • Creates multiple useful tags (latest, <short-commit>)

    • Shows build information and results

    • Uses the same arguments as CI/CD builds

    Verify Image Labels

    # View git commit hash
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

    Docker: MCP Client Configuration

    Once the image is built, configure your MCP client to use it:

    {
  "mcpServers": {
    "couchbase": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CB_CONNECTION_STRING=couchbases://your-connection-string",
        "-e", "CB_USERNAME=your-username",
        "-e", "CB_PASSWORD=your-password",
        "mcp/couchbase-src"
      ]
    }
  }
}

    Next Steps

    See the Quick Start for client-specific configuration instructions.