> ## Documentation Index
> Fetch the complete documentation index at: https://www.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install, Configure, and Connect to the CockroachDB MCP Server

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

This page shows how to install the <InternalLink path="cockroachdb-mcp-server">CockroachDB MCP Server</InternalLink>, connect it to a cluster, and configure your AI tools to use it.

<Danger>
  AI tools with cluster access can execute operations on your behalf. When first connecting an AI tool to CockroachDB, consider starting with a staging cluster to understand the tool's behavior before granting it access to production data.
</Danger>

## Before you begin

* To install with `go install` or build from source, ensure that you have Go 1.26 or later.
* Ensure that you have a reachable CockroachDB cluster. For a multi-node cluster, connect through a <InternalLink path="recommended-production-settings#load-balancing">load balancer</InternalLink>; for development, you can connect to any node directly. The default port is `26257`.
* Create a dedicated <InternalLink path="create-user">SQL user</InternalLink> for the server, and issue <InternalLink path="cockroach-cert">client certificates</InternalLink> for it.
  * <InternalLink path="grant">Grant</InternalLink> the user only the privileges that the tools you plan to use need. For example, grant `SELECT` on the relevant databases for read-only use. Avoid `admin` and write privileges unless you plan to enable the <InternalLink path="cockroachdb-mcp-server-reference#write-tools">write tools</InternalLink>.

## Step 1. Install the server

<Tabs>
  <Tab title="Mac">
    Pre-built binaries are not available for macOS because a CockroachDB parser dependency requires cgo on macOS. Use one of the following options instead.

    ### Option 1: `go install`

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    go install github.com/cockroachdb/cockroachdb-mcp-server@latest
    ```

    The binary lands in `$(go env GOPATH)/bin/cockroachdb-mcp-server`.

    ### Option 2: Build from source

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    git clone https://github.com/cockroachdb/cockroachdb-mcp-server
    cd cockroachdb-mcp-server
    go build -o bin/cockroachdb-mcp-server .
    ./bin/cockroachdb-mcp-server --version
    ```

    ### Option 3: Docker

    Pull the multi-arch image (`linux/amd64`, `linux/arm64`) from Google Artifact Registry:

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    docker pull us-docker.pkg.dev/releases-prod/cockroachdb-mcp-server/cockroachdb-mcp-server:{version}
    ```

    The image runs as `nonroot` on a [distroless](https://github.com/GoogleContainerTools/distroless) base image. On Apple Silicon, Docker runs the `linux/arm64` image natively. This is the only install option on macOS that does not require Go.

    To configure an MCP client to run the image, refer to the Docker configuration in [Step 2](#step-2-configure-your-mcp-client).
  </Tab>

  <Tab title="Linux">
    ### Option 1: Pre-built binaries

    Download a tarball for `linux/amd64` or `linux/arm64` from the [GitHub Releases page](https://github.com/cockroachdb/cockroachdb-mcp-server/releases).

    ### Option 2: `go install`

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    go install github.com/cockroachdb/cockroachdb-mcp-server@latest
    ```

    The binary lands in `$(go env GOPATH)/bin/cockroachdb-mcp-server`.

    ### Option 3: Build from source

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    git clone https://github.com/cockroachdb/cockroachdb-mcp-server
    cd cockroachdb-mcp-server
    go build -o bin/cockroachdb-mcp-server .
    ./bin/cockroachdb-mcp-server --version
    ```

    ### Option 4: Docker

    Pull the multi-arch image (`linux/amd64`, `linux/arm64`) from Google Artifact Registry:

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    docker pull us-docker.pkg.dev/releases-prod/cockroachdb-mcp-server/cockroachdb-mcp-server:{version}
    ```

    The image runs as `nonroot` on a [distroless](https://github.com/GoogleContainerTools/distroless) base image.

    To configure an MCP client to run the image, refer to the Docker configuration in [Step 2](#step-2-configure-your-mcp-client).
  </Tab>

  <Tab title="Windows">
    ### Option 1: Pre-built binaries

    Download a `.zip` archive for `windows/amd64` or `windows/arm64` from the [GitHub Releases page](https://github.com/cockroachdb/cockroachdb-mcp-server/releases).

    ### Option 2: `go install`

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    go install github.com/cockroachdb/cockroachdb-mcp-server@latest
    ```

    The binary lands in `%GOPATH%\bin\cockroachdb-mcp-server.exe`.

    ### Option 3: Build from source

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    git clone https://github.com/cockroachdb/cockroachdb-mcp-server
    cd cockroachdb-mcp-server
    go build -o bin\cockroachdb-mcp-server.exe .
    bin\cockroachdb-mcp-server.exe --version
    ```

    ### Option 4: Docker

    Pull the multi-arch image (`linux/amd64`, `linux/arm64`) from Google Artifact Registry:

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    docker pull us-docker.pkg.dev/releases-prod/cockroachdb-mcp-server/cockroachdb-mcp-server:{version}
    ```

    The image is built for Linux; on Windows, run it with [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/). The image runs as `nonroot` on a [distroless](https://github.com/GoogleContainerTools/distroless) base image.

    To configure an MCP client to run the image, refer to the Docker configuration in [Step 2](#step-2-configure-your-mcp-client).
  </Tab>
</Tabs>

## Step 2. Configure your MCP client

Each server instance connects to a single cluster. To give your AI tool access to multiple clusters, add one `mcpServers` entry per cluster, each pointing at its own server instance.

<Tabs>
  <Tab title="stdio (default)">
    In stdio mode, your AI tool launches the server as a subprocess, so all configuration is passed in the `env` block of the tool's MCP configuration. Add one of the following to your MCP client's configuration file, replacing the example values with your own host, user, and certificate paths. Most MCP clients read an `mcpServers` block or an equivalent. Refer to your client's documentation for the file location and format.

    <Note>
      GUI clients such as Claude Desktop often launch with a minimal `PATH` and do not expand `~`, so a bare `command` may not resolve. Use the absolute path to the binary instead, for example `/Users/{username}/go/bin/cockroachdb-mcp-server`.
    </Note>

    ### Specify configuration variables

    #### Certificate authentication (recommended)

    Use <InternalLink path="cockroachdb-mcp-server-reference#authentication">individual variables</InternalLink> to connect with client certificates:

    ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    {
      "mcpServers": {
        "cockroachdb": {
          "command": "cockroachdb-mcp-server",
          "env": {
            "CRDB_HOST": "my-cluster.crdb.io",
            "CRDB_USERNAME": "ai_agent",
            "CRDB_SSL_MODE": "verify-full",
            "CRDB_SSL_CA_PATH": "/certs/ca.crt",
            "CRDB_SSL_CERTFILE": "/certs/client.ai_agent.crt",
            "CRDB_SSL_KEYFILE": "/certs/client.ai_agent.key"
          }
        }
      }
    }
    ```

    #### Connection string

    Use <InternalLink path="cockroachdb-mcp-server-reference#crdb-database-url">`CRDB_DATABASE_URL`</InternalLink> to pass all connection parameters in a single string:

    ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    {
      "mcpServers": {
        "cockroachdb": {
          "command": "cockroachdb-mcp-server",
          "env": {
            "CRDB_DATABASE_URL": "postgresql://ai_agent@my-cluster.crdb.io:26257/defaultdb?sslmode=verify-full&sslcert=/certs/client.ai_agent.crt&sslkey=/certs/client.ai_agent.key&sslrootcert=/certs/ca.crt"
          }
        }
      }
    }
    ```

    <InternalLink path="cockroachdb-mcp-server-reference#crdb-database-url">`CRDB_DATABASE_URL`</InternalLink> must include an `sslmode` of `require`, `verify-ca`, or `verify-full`. A connection string that omits `sslmode` is rejected at startup.

    #### Local insecure cluster (development only)

    For a local cluster started with `cockroach start-single-node --insecure` or <InternalLink path="cockroach-demo">`cockroach demo --insecure`</InternalLink>, opt in to a TLS-free connection. No certificate files are needed:

    ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    {
      "mcpServers": {
        "cockroachdb": {
          "command": "cockroachdb-mcp-server",
          "env": {
            "CRDB_DATABASE_URL": "postgresql://root@localhost:26257/defaultdb?sslmode=disable",
            "CRDB_MCP_ALLOW_INSECURE_DB": "true",
            "CRDB_MCP_ENABLE_WRITE_QUERIES": "true"
          }
        }
      }
    }
    ```

    For the full list of configuration options, refer to the <InternalLink path="cockroachdb-mcp-server-reference#configuration">CockroachDB MCP Server Reference</InternalLink>.

    ### Docker

    To run the Docker image in stdio mode, set `command` to `docker` and move all configuration into `args`: pass `run`, `--rm`, and `-i`, followed by each environment variable with `-e`, and the image reference last. The same `CRDB_*` variables apply unchanged. Because the server runs inside the container, mount the host certificate directory read-only and point the `CRDB_SSL_*` paths at the in-container mount location:

    ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    {
      "mcpServers": {
        "cockroachdb": {
          "command": "docker",
          "args": [
            "run", "--rm", "-i",
            "-e", "CRDB_HOST=my-cluster.crdb.io",
            "-e", "CRDB_USERNAME=ai_agent",
            "-e", "CRDB_SSL_MODE=verify-full",
            "-e", "CRDB_SSL_CA_PATH=/certs/ca.crt",
            "-e", "CRDB_SSL_CERTFILE=/certs/client.ai_agent.crt",
            "-e", "CRDB_SSL_KEYFILE=/certs/client.ai_agent.key",
            "-v", "/path/to/certs:/certs:ro",
            "us-docker.pkg.dev/releases-prod/cockroachdb-mcp-server/cockroachdb-mcp-server:{version}"
          ]
        }
      }
    }
    ```

    In this example, `/path/to/certs` is the certificate directory on the host, and `/certs` is where it is mounted inside the container.

    A connection string translates the same way: keep the read-only mount, and use the in-container `/certs` paths in the `sslcert`, `sslkey`, and `sslrootcert` parameters of `CRDB_DATABASE_URL`.

    For a local insecure cluster, `localhost` inside the container refers to the container itself, not the host. On macOS and Windows, use `host.docker.internal` in place of `localhost` in the connection string. On Linux, add `"--network", "host"` to `args` and keep `localhost`.
  </Tab>

  <Tab title="HTTP">
    For shared or remote deployments, run the server as a long-lived process using the HTTP transport, and point each MCP client at its URL. Replace the example strings with your own. For the full list of <InternalLink path="cockroachdb-mcp-server-reference#transport">transport variables</InternalLink>, refer to the reference page.

    In HTTP mode, one server instance binds to exactly one cluster and one SQL user, so every client that connects shares that user's privileges. When multiple projects share a cluster, run a separate instance per project, each with its own least-privilege SQL user and bearer token.

    1. Export the server configuration and start the server:

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       export CRDB_DATABASE_URL="postgresql://..."
       export CRDB_MCP_TRANSPORT=http
       export CRDB_MCP_HTTP_LISTEN_ADDR=0.0.0.0:8443
       export CRDB_MCP_BEARER_TOKEN="$(openssl rand -hex 32)"
       export CRDB_MCP_TLS_CERT=/etc/mcp/tls.crt
       export CRDB_MCP_TLS_KEY=/etc/mcp/tls.key
       cockroachdb-mcp-server
       ```

       Set <InternalLink path="cockroachdb-mcp-server-reference#crdb-mcp-http-listen-addr">`CRDB_MCP_HTTP_LISTEN_ADDR`</InternalLink> to the `host:port` that fits your deployment: for example, `127.0.0.1:9090` to serve only local traffic behind a TLS-terminating reverse proxy (with <InternalLink path="cockroachdb-mcp-server-reference#crdb-mcp-allow-insecure-http">`CRDB_MCP_ALLOW_INSECURE_HTTP`</InternalLink>`=true`), or `10.0.0.5:8443` to bind a specific interface.

       HTTP mode is TLS-by-default: the server refuses to start without <InternalLink path="cockroachdb-mcp-server-reference#crdb-mcp-tls-cert">`CRDB_MCP_TLS_CERT`</InternalLink> and <InternalLink path="cockroachdb-mcp-server-reference#crdb-mcp-tls-key">`CRDB_MCP_TLS_KEY`</InternalLink> unless <InternalLink path="cockroachdb-mcp-server-reference#crdb-mcp-allow-insecure-http">`CRDB_MCP_ALLOW_INSECURE_HTTP`</InternalLink>`=true` is set (for deployments behind a TLS-terminating reverse proxy). The `/healthz` and `/ready` endpoints are unauthenticated `GET`/`HEAD` probes; all other paths require the bearer token.

    2. Add the server URL and bearer token to your MCP client's configuration:

       ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       {
         "mcpServers": {
           "cockroachdb": {
             "type": "http",
             "url": "https://mcp.example.com:8443",
             "headers": {
               "Authorization": "Bearer {token}"
             }
           }
         }
       }
       ```
  </Tab>
</Tabs>

## Step 3. Verify the connection

Restart your AI tool so that it registers the new MCP configuration, then send a prompt that exercises a read tool. For example:

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
List all of the databases in my CockroachDB cluster.
```

## See also

* <InternalLink path="cockroachdb-mcp-server">CockroachDB MCP Server</InternalLink>
* <InternalLink path="cockroachdb-mcp-server-reference">CockroachDB MCP Server Reference</InternalLink>
* <InternalLink version="cockroachcloud" path="connect-to-the-cockroachdb-cloud-mcp-server">Connect to the CockroachDB Cloud MCP Server</InternalLink>