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

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

This page shows how to install the [CockroachDB MCP Server](https://docs.cockroachlabs.com/docs/stable/cockroachdb-mcp-server.md), connect it to a cluster, and configure your AI tools to use it.

> [!CAUTION]
>
> 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.

## 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 [load balancer](https://docs.cockroachlabs.com/docs/stable/recommended-production-settings.md#load-balancing); for development, you can connect to any node directly. The default port is `26257`.
* Create a dedicated [SQL user](https://docs.cockroachlabs.com/docs/stable/create-user.md) for the server, and issue [client certificates](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md) for it.
  * [Grant](https://docs.cockroachlabs.com/docs/stable/grant.md) 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 [write tools](https://docs.cockroachlabs.com/docs/stable/cockroachdb-mcp-server-reference.md#write-tools).

## Step 1. Install the server

**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).

**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).

**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).

## 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.

**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`.

### Specify configuration variables

#### Certificate authentication (recommended)

Use [individual variables](https://docs.cockroachlabs.com/docs/stable/cockroachdb-mcp-server-reference.md#authentication) 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 [`CRDB_DATABASE_URL`](https://docs.cockroachlabs.com/docs/stable/cockroachdb-mcp-server-reference#crdb-database-url) 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"
      }
    }
  }
}
```

[`CRDB_DATABASE_URL`](https://docs.cockroachlabs.com/docs/stable/cockroachdb-mcp-server-reference#crdb-database-url) 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 [`cockroach demo --insecure`](https://docs.cockroachlabs.com/docs/stable/cockroach-demo), 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 [CockroachDB MCP Server Reference](https://docs.cockroachlabs.com/docs/stable/cockroachdb-mcp-server-reference.md#configuration).

### 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`.

**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 [transport variables](https://docs.cockroachlabs.com/docs/stable/cockroachdb-mcp-server-reference.md#transport), 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 [`CRDB_MCP_HTTP_LISTEN_ADDR`](https://docs.cockroachlabs.com/docs/stable/cockroachdb-mcp-server-reference#crdb-mcp-http-listen-addr) 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 [`CRDB_MCP_ALLOW_INSECURE_HTTP`](https://docs.cockroachlabs.com/docs/stable/cockroachdb-mcp-server-reference#crdb-mcp-allow-insecure-http)`=true`), or `10.0.0.5:8443` to bind a specific interface.

   HTTP mode is TLS-by-default: the server refuses to start without [`CRDB_MCP_TLS_CERT`](https://docs.cockroachlabs.com/docs/stable/cockroachdb-mcp-server-reference#crdb-mcp-tls-cert) and [`CRDB_MCP_TLS_KEY`](https://docs.cockroachlabs.com/docs/stable/cockroachdb-mcp-server-reference#crdb-mcp-tls-key) unless [`CRDB_MCP_ALLOW_INSECURE_HTTP`](https://docs.cockroachlabs.com/docs/stable/cockroachdb-mcp-server-reference#crdb-mcp-allow-insecure-http)`=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}"
         }
       }
     }
   }
   ```

## 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

* [CockroachDB MCP Server](https://docs.cockroachlabs.com/docs/stable/cockroachdb-mcp-server.md)
* [CockroachDB MCP Server Reference](https://docs.cockroachlabs.com/docs/stable/cockroachdb-mcp-server-reference.md)
* [Connect to the CockroachDB Cloud MCP Server](https://docs.cockroachlabs.com/docs/cockroachcloud/connect-to-the-cockroachdb-cloud-mcp-server.md)