Install, Configure, and Connect to the CockroachDB MCP Server

This page shows how to install the , connect it to a cluster, and configure your AI tools to use it.

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 ; for development, you can connect to any node directly. The default port is 26257.
Create a dedicated for the server, and issue for it.
- 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 .

Step 1. Install the server

Mac
Linux
Windows

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`

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

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:

docker pull us-docker.pkg.dev/releases-prod/cockroachdb-mcp-server/cockroachdb-mcp-server:{version}

The image runs as nonroot on a 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.

Option 1: Pre-built binaries

Download a tarball for linux/amd64 or linux/arm64 from the GitHub Releases page.

Option 2: `go install`

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

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:

docker pull us-docker.pkg.dev/releases-prod/cockroachdb-mcp-server/cockroachdb-mcp-server:{version}

The image runs as nonroot on a distroless base image.To configure an MCP client to run the image, refer to the Docker configuration in Step 2.

Option 1: Pre-built binaries

Download a .zip archive for windows/amd64 or windows/arm64 from the GitHub Releases page.

Option 2: `go install`

go install github.com/cockroachdb/cockroachdb-mcp-server@latest

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

Option 3: Build from source

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:

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. The image runs as nonroot on a 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

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)
HTTP

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.

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 to connect with client certificates:

{
  "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 to pass all connection parameters in a single string:

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

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 , opt in to a TLS-free connection. No certificate files are needed:

{
  "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 .

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:

{
  "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.

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

Export the server configuration and start the server:
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 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 =true), or 10.0.0.5:8443 to bind a specific interface. HTTP mode is TLS-by-default: the server refuses to start without and unless =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.

Add the server URL and bearer token to your MCP client’s configuration:

{
  "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:

List all of the databases in my CockroachDB cluster.

Get Started

CockroachDB and AI

Feature Overview

Data Resilience

Connect to an Application

Self-Hosted Deployments

Schema Design

Reads and Writes

Stream Data

Cross-Cluster Replication

Multi-Region Capabilities

Optimize Performance

Integrate

Install, Configure, and Connect to the CockroachDB MCP Server

Before you begin

Step 1. Install the server

Option 1: `go install`

Option 2: Build from source

Option 3: Docker

Option 1: Pre-built binaries

Option 2: `go install`

Option 3: Build from source

Option 4: Docker

Option 1: Pre-built binaries

Option 2: `go install`

Option 3: Build from source

Option 4: Docker

Step 2. Configure your MCP client

Specify configuration variables

Certificate authentication (recommended)

Connection string

Local insecure cluster (development only)

Docker

Step 3. Verify the connection

See also

​Before you begin

​Step 1. Install the server

​Option 1: go install

​Option 2: Build from source

​Option 3: Docker

​Option 1: Pre-built binaries

​Option 2: go install

​Option 3: Build from source

​Option 4: Docker

​Option 1: Pre-built binaries

​Option 2: go install

​Option 3: Build from source

​Option 4: Docker

​Step 2. Configure your MCP client

​Specify configuration variables

​Certificate authentication (recommended)

​Connection string

​Local insecure cluster (development only)

​Docker

​Step 3. Verify the connection

​See also

Before you begin

Step 1. Install the server

Option 1: `go install`

Option 2: Build from source

Option 3: Docker

Option 1: Pre-built binaries

Option 2: `go install`

Option 3: Build from source

Option 4: Docker

Option 1: Pre-built binaries

Option 2: `go install`

Option 3: Build from source

Option 4: Docker

Step 2. Configure your MCP client

Specify configuration variables

Certificate authentication (recommended)

Connection string

Local insecure cluster (development only)

Docker

Step 3. Verify the connection

See also