CockroachDB MCP Server

The CockroachDB MCP Server connects AI assistants such as Claude Code or Cursor to a CockroachDB cluster. With it the assistant can list databases and tables, read schemas, run and explain queries, and, if you want, write data too. The server comes from Cockroach Labs, the maker of the database, and is published as an open-source project under the Apache License 2.0. The documentation describes it as access for AI tools and agents that need to reach an existing cluster.

What is the CockroachDB MCP Server?

CockroachDB is a distributed SQL database that speaks the PostgreSQL protocol and is built for resilience. MCP is an open standard through which an assistant calls the tools of an external service. The server translates the assistant's calls into SQL statements against your cluster. According to the documentation it runs by default as a local subprocess of your AI tool (stdio), so each person works with their own SQL credentials. Alternatively it can run as a long-lived HTTP service that several clients reach over HTTPS with a bearer token.

Which tools are available?

Without further settings ten read tools are active: list databases and tables, read a table's schema, retrieve cluster information and nodes, show SQL users, inspect running queries and statements, run SELECT queries, and produce execution plans with EXPLAIN. Write tools exist only if you set the environment variable CRDB_MCP_ENABLE_WRITE_QUERIES to true: create databases and tables, and insert, update, and delete rows. According to the documentation update and delete always require a WHERE condition. List tools return at most 100 rows by default, and a SELECT without a limit automatically gets one appended.

What is it particularly useful for?

The value lies in working with an unfamiliar or grown schema. Instead of describing tables by hand, you let the assistant read the schema and derive queries, migrations, or index suggestions from it. With the explain tool it checks how the cluster would run a query, and through the view of running queries it helps hunt for long runners. For developers building against CockroachDB this is faster than keeping SQL clients and documentation open side by side.

Setup

You need a CockroachDB cluster and a SQL user. Installation is with go install github.com/cockroachdb/cockroachdb-mcp-server@latest (according to the documentation from Go 1.26), via prebuilt binaries for Linux and Windows, a Docker image, or from source. The connection is configured exclusively through environment variables, such as CRDB_HOST, CRDB_USERNAME, and the paths to certificates. You then register the command as a stdio server in your MCP client.

Security and limits

The defaults are strict: sessions are read-only, password sign-in is rejected by default, certificate sign-in is recommended, and the connection requires TLS. In HTTP mode the server, according to the documentation, does not start without a certificate and key. Queries run at low priority by default so agent load does not displace production load, and a 30-second timeout cancels long queries. The repository stresses that the SQL role, not the server, is the real security boundary: never connect as root or administrator. Results enter the AI client's context and therefore reach the model provider.

Costs

The server is free and open source but requires a CockroachDB cluster. According to the pricing page CockroachDB Cloud comes in the Standard and Mission Critical editions, billed by compute usage, with a time-limited trial with credit for new organizations. According to the documentation the cloud has its own MCP server with separate setup. Current terms are on the official pricing page.

Who is the CockroachDB MCP Server for?

It is worthwhile for teams that already use CockroachDB and want to speed up schema work, query analysis, and troubleshooting with an assistant. Anyone who only wants to read gets a safe setup with the defaults. Anyone who enables the write tools should use a tightly limited SQL role and a test environment. Without a CockroachDB cluster the server is of no use.

A CockroachDB cluster, a SQL user with narrow privileges, Go 1.26 or newer for go install (alternatively a binary or Docker image), and an MCP client such as Claude Code or Cursor.

With the CockroachDB MCP Server, an AI assistant reads schemas of your cluster and runs queries. This guide leads from installation to the first query.

Step 1: Check the prerequisites

You need a CockroachDB cluster, a SQL user, and an MCP client such as Claude Code or Cursor. For installation with go install the documentation requires Go 1.26 or newer. Alternatively there are binaries for Linux and Windows and a Docker image.

go install

Step 2: Create a SQL role with narrow privileges

According to the repository the SQL role is the real security boundary. So create a dedicated role that may only read, and never connect as root or administrator. For tests, a development cluster is better.

Step 3: Install the server

Run go install github.com/cockroachdb/cockroachdb-mcp-server@latest. On macOS, according to the repository, only go install or building from source remains because no prebuilt binary is offered.

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

Step 4: Configure the connection

Configuration runs through environment variables. Set CRDB_HOST to the address of your load balancer, CRDB_USERNAME to the role, and the paths to CA, client certificate, and key. Password sign-in is blocked by default; the default for TLS checking is verify-full.

Step 5: Register it in the MCP client

Register the program as a stdio server and pass the environment variables in the entry. The HTTP mode with bearer token and TLS only pays off when several people should share one service.

Step 6: First queries

Ask for the tables of a database or have the schema of a table described. Then have a query checked with EXPLAIN or show running queries. A SELECT without a limit automatically gets one.

Step 7: Enable write tools deliberately

By default only read tools are active. Only with CRDB_MCP_ENABLE_WRITE_QUERIES=true do tools for creating, inserting, updating, and deleting appear. Do this only in a test environment and with a tightly limited role.

SQL access to the cluster, recommended via certificate; password only after explicit opt-in. In HTTP mode additionally a bearer token of at least 16 characters.

By default read-only tools in read-only sessions; write and DDL tools only with CRDB_MCP_ENABLE_WRITE_QUERIES=true. The privileges of the SQL role remain decisive.

The server runs locally or in your own environment. Queried data enters the AI client context and therefore reaches the model provider.

Unwanted writes when write tools are enabled or SQL privileges are too broad, passing business data to the model provider, and credentials stored in the repository.