CockroachDB MCP Server

1# CockroachDB MCP Server
2[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
3[![Python Version](https://img.shields.io/badge/python-3.13%2B-blue)](https://www.python.org/downloads/)
4[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blue)](https://mcp.so/server/cockroachdb-mcp-server/cockroachdb)
5[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/amineelkouhen/mcp-cockroachdb)](https://archestra.ai/mcp-catalog/amineelkouhen__mcp-cockroachdb)
6 
7## Overview
8 
9The CockroachDB MCP Server is a **natural language interface** designed for LLMs and agentic applications to manage, monitor, and query data in CockroachDB. It integrates seamlessly with **MCP (Model Content Protocol)** clients, such as Claude Desktop or Cursor, enabling AI-driven workflows to interact directly with your database. 
10 
11## Table of Contents
12- [Overview](#overview)
13- [Features](#features)
14- [Tools](#tools)
15  - [Cluster Monitoring](#cluster-monitoring)
16  - [Database Operations](#database-operations)
17  - [Table Management](#table-management)
18  - [Query Engine](#query-engine)
19- [Installation](#installation)
20  - [Quick Start with uvx](#quick-start-with-uvx)
21  - [Development Installation](#development-installation)
22  - [With Docker](#with-docker)
23- [Configuration](#configuration)
24  - [Configuration via command line arguments](#configuration-via-command-line-arguments)
25  - [Configuration via Environment Variables](#configuration-via-environment-variables)
26- [Integrations](#integrations)
27  - [OpenAI Agents SDK](#openai-agents-sdk)
28  - [Augment](#augment)
29  - [Claude Desktop](#claude-desktop)
30  - [VS Code with GitHub Copilot](#vs-code-with-github-copilot)
31  - [Cursor](#cursor)
32- [Testing](#testing)
33- [Contributing](#contributing)
34- [License](#license)
35- [Quality Badge](#quality-badge)
36- [Contact](#contact)
37 
38## Features
39- **Natural Language Queries**: Enables AI agents to query and create transactions using natural language, supporting complex workflows.
40- **Search & Filtering**: Supports efficient data retrieval and searching in CockroachDB.
41- **Cluster Monitoring**: Check and monitor the CockroachDB cluster status, including node health and replication.
42- **Database Operations**: Perform all operations related to databases, such as creation, deletion, and configuration.
43- **Table Management**: Handle tables, indexes, and schemas for flexible data modeling.
44- **Seamless MCP Integration**: Works with any **MCP client** for smooth communication.
45- **Scalable & Lightweight**: Designed for **high-performance** data operations.
46 
47## Tools
48 
49The CockroachDB MCP Server Server provides tools to manage the data stored in CockroachDB. 
50 
51![architecture](https://github.com/user-attachments/assets/36a121d9-48b7-4840-9317-002a38441b8d)
52 
53The tools are organized into four main categories:
54 
55### Cluster Monitoring
56 
57Purpose:
58Provides tools for monitoring and managing CockroachDB clusters.
59 
60Summary:
61- Get cluster health and node status.
62- Show currently running queries.
63- Analyze query performance statistics.
64- Retrieve replication and distribution status for tables or the whole database.
65- Get query execution insights with optional keyword filtering.
66- Find slow queries from statement statistics with optional keyword filtering.
67- Get transaction execution insights with optional keyword filtering.
68- View contention events with optional table filtering.
69- Get index recommendations from query insights.
70 
71### Database Operations
72 
73Purpose:
74Handles database-level operations and connection management.
75 
76Summary:
77- Connect to a CockroachDB database.
78- List, create, drop, and switch databases.
79- Get connection status and active sessions.
80- Retrieve database settings.
81 
82### Table Management
83 
84Purpose:
85Provides tools for managing tables, indexes, views, and schema relationships in CockroachDB.
86 
87Summary:
88- Create, drop, and describe tables and views.
89- Bulk import data into tables.
90- Manage indexes (create/drop).
91- List tables, views, and table relationships.
92- Analyze schema structure and metadata.
93 
94### Query Engine
95 
96Purpose:
97Executes and manages SQL queries and transactions.
98 
99Summary:
100- Execute SQL queries with formatting options (JSON, CSV, table).
101- Run multi-statement transactions.
102- Explain query plans for optimization.
103- Track and retrieve query history.
104 
105## Installation
106 
107The CockroachDB MCP Server supports the `stdio` [transport](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio) and the `streamable-http` transport.
108 
109### Quick Start with uvx 
110 
111The easiest way to use the CockroachDB MCP Server is with `uvx`, which allows you to run it directly from GitHub (from a branch, or use a tagged release). It is recommended to use a tagged release. The `main` branch is under active development and may contain breaking changes. As an example, you can execute the following command to run the `0.1.0` release:
112 
113```commandline
114uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git@0.1.0 cockroachdb-mcp-server --url postgresql://localhost:26257/defaultdb
115```
116 
117Check the release notes for the latest version in the [Releases](https://github.com/amineelkouhen/mcp-cockroachdb/releases) section.
118Additional examples are provided below.
119 
120```sh
121# Run with CockroachDB URI
122uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --url postgresql://localhost:26257/defaultdb
123 
124# Run with individual parameters
125uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --host localhost --port 26257 --database defaultdb --user root --password mypassword
126 
127# See all options
128uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --help
129 
130# Run with streamable HTTP transport
131uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
132  --url postgresql://localhost:26257/defaultdb \
133  --transport http \
134  --http-host 0.0.0.0 \
135  --http-port 8000 \
136  --http-path /mcp
137```
138 
139### Development Installation
140 
141For development or if you prefer to clone the repository:
142 
143```sh
144# Clone the repository
145git clone https://github.com/amineelkouhen/mcp-cockroachdb.git
146cd mcp-cockroachdb
147 
148# Install dependencies using uv
149uv venv
150source .venv/bin/activate
151uv sync
152 
153# Run with CLI interface
154uv run cockroachdb-mcp-server --help
155 
156# Or run the main file directly (uses environment variables)
157uv run src/main.py
158```
159 
160Once you cloned the repository, installed the dependencies and verified you can run the server, you can configure Claude Desktop or any other MCP Client to use this MCP Server running the main file directly (it uses environment variables). This is usually preferred for development.
161The following example is for Claude Desktop, but the same applies to any other MCP Client.
162 
1631. Specify your CockroachDB credentials and TLS configuration
1642. Retrieve your `uv` command full path (e.g. `which uv`)
1653. Edit the `claude_desktop_config.json` configuration file
166   - on a MacOS, at `~/Library/Application Support/Claude/`
167 
168```json
169{
170    "mcpServers": {
171        "cockroach": {
172            "command": "<full_path_uv_command>",
173            "args": [
174                "--directory",
175                "<your_mcp_server_directory>",
176                "run",
177                "src/main.py"
178            ],
179            "env": {
180                "CRDB_HOST": "<your_cockroachdb_hostname>",
181                "CRDB_PORT": "<your_cockroachdb_port>",
182                "CRDB_DATABASE": "<your_cockroach_database>",
183                "CRDB_USERNAME": "<your_cockroachdb_user>",
184                "CRDB_PWD": "<your_cockroachdb_password>",
185                "CRDB_SSL_MODE": "disable|allow|prefer|require|verify-ca|verify-full",
186                "CRDB_SSL_CA_PATH": "<your_cockroachdb_ca_path>",
187                "CRDB_SSL_KEYFILE": "<your_cockroachdb_keyfile_path>",
188                "CRDB_SSL_CERTFILE": "<your_cockroachdb_certificate_path>",
189            }
190        }
191    }
192}
193```
194 
195You can troubleshoot problems by tailing the log file.
196 
197```commandline
198tail -f ~/Library/Logs/Claude/mcp-server-cockroach.log
199```
200 
201### With Docker Compose (Local Development)
202 
203For local development and testing, use the provided `docker-compose.yaml` to spin up both CockroachDB and the MCP server:
204 
205```bash
206# Start CockroachDB and MCP server
207docker compose up -d
208 
209# The MCP server is available at http://localhost:8000/mcp/
210# CockroachDB UI is available at http://localhost:8080
211 
212# View logs
213docker compose logs -f mcp-server
214 
215# Stop and clean up
216docker compose down -v
217```
218 
219### With Docker
220 
221You can use a dockerized deployment of this server. You can either build your image or use the official [CockroachDB MCP Docker](https://hub.docker.com/r/mcp/cockroachdb) image.
222 
223If you'd like to build your image, the CockroachDB MCP Server provides a Dockerfile. Build this server's image with:
224 
225```commandline
226docker build -t mcp-cockroachdb .
227```
228 
229Finally, configure the client to create the container at start-up. An example for Claude Desktop is provided below. Edit the `claude_desktop_config.json` and add:
230 
231```json
232{
233  "mcpServers": {
234    "cockroach": {
235      "command": "docker",
236      "args": ["run",
237                "--rm",
238                "--name",
239                "cockroachdb-mcp-server",
240                "-e", "CRDB_HOST=<cockroachdb_host>",
241                "-e", "CRDB_PORT=<cockroachdb_port>",
242                "-e", "CRDB_DATABASE=<cockroachdb_database>",
243                "-e", "CRDB_USERNAME=<cockroachdb_user>",
244                "mcp-cockroachdb"]
245    }
246  }
247}
248```
249 
250To use the [CockroachDB MCP Docker](https://hub.docker.com/mcp/server/cockroachdb) image, just replace your image name (`mcp-cockroachdb` in the example above) with `mcp/cockroachdb`.
251 
252## Configuration
253 
254The CockroachDB MCP Server can be configured in two ways: either via command-line arguments or via environment variables.
255The precedence is: CLI arguments > environment variables > default values.
256 
257### Configuration via command line arguments
258 
259When using the CLI interface, you can configure the server with command line arguments:
260 
261```sh
262# Basic CockroachDB connection
263uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
264  --host localhost \
265  --port 26257 \
266  --db defaultdb \
267  --user root \
268  --password mypassword
269 
270# Using CockroachDB URI (simpler)
271uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
272  --url postgresql://root@localhost:26257/defaultdb
273 
274# SSL connection
275uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
276  --url postgresql://user:pass@cockroach.example.com:26257/defaultdb?sslmode=verify-full&sslrootcert=path/to/ca.crt&sslcert=path/to/client.username.crt&sslkey=path/to/client.username.key
277 
278# See all available options
279uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --help
280```
281 
282**Available CLI Options:**
283- `--url` - CockroachDB connection URI (postgresql://user:pass@host:port/db)
284- `--host` - CockroachDB hostname 
285- `--port` - CockroachDB port (default: 26257)
286- `--db` - CockroachDB database name (default: defaultdb)
287- `--user` - CockroachDB username
288- `--password` - CockroachDB password
289- `--ssl-mode` - SSL mode - Possible values: require, verify-ca, verify-full, disable (default)
290- `--ssl-key` - Path to SSL Client key file
291- `--ssl-cert` - Path to SSL Client certificate file
292- `--ssl-ca-cert` - Path to CA (Root) certificate file'
293- `--transport` - MCP transport to use (`stdio` or `http`)
294- `--http-host` - HTTP host to bind for streamable HTTP transport
295- `--http-port` - HTTP port to bind for streamable HTTP transport
296- `--http-path` - HTTP path for streamable HTTP transport (e.g., /mcp)
297- `--stateless-http` - Enable stateless HTTP mode for horizontal scaling
298- `--use-env` - Use environment variables for CockroachDB configuration
299 
300### Configuration via Environment Variables
301 
302If desired, you can use environment variables. Defaults are provided for all variables.
303 
304| Name                 | Description                                                                    | Default Value    |
305|----------------------|--------------------------------------------------------------------------------|------------------|
306| `CRDB_HOST`          | The host name or address of a CockroachDB node or load balancer.               | 127.0.0.1        |
307| `CRDB_PORT`          | The port number of the SQL interface of the CockroachDB node or load balancer. | 26257            |
308| `CRDB_DATABASE`      | A database name to use as the current database.                                | defaultdb        |
309| `CRDB_USERNAME`      | The SQL user that will own the client session.                                 | root             |
310| `CRDB_PWD`           | The user's password.                                                           | None             |
311| `CRDB_SSL_MODE`      | Which type of secure connection to use.                                        | disable          |
312| `CRDB_SSL_CA_PATH`   | Path to the CA certificate, when sslmode is not `disable`.                     | None             |
313| `CRDB_SSL_CERTFILE`  | Path to the client certificate, when sslmode is not `disable`.                 | None             |
314| `CRDB_SSL_KEYFILE`   | Path to the client private key, when sslmode is not `disable`.                 | None             |
315 
316There are several ways to set environment variables:
317 
3181. **Using a `.env` File**:  
319Place a `.env` file in your project directory with key-value pairs for each environment variable. Tools like `python-dotenv`, `pipenv`, and `uv` can automatically load these variables when running your application. This is a convenient and secure way to manage configuration, as it keeps sensitive data out of your shell history and version control (if `.env` is in `.gitignore`).
320For example, create a `.env` file with the following content from the `.env.example` file provided in the repository:
321 
322```bash
323cp .env.example .env
324```
325 
326Then edit the `.env` file to set your CockroachDB configuration:
327 
328OR,
329 
3302. **Setting Variables in the Shell**:  
331You can export environment variables directly in your shell before running your application. For example:
332 
333```sh
334export CRDB_URL= postgresql://root@127.0.0.1:26257/defaultdb
335```
336 
337This method is helpful for temporary overrides or quick testing.
338 
339## Integrations
340 
341Integrating this MCP Server with development frameworks like OpenAI Agents SDK or using tools like Claude Desktop, VS Code, or Augment is described in the following sections.
342 
343### OpenAI Agents SDK
344 
345Integrate this MCP Server with the OpenAI Agents SDK. Read the [documents](https://openai.github.io/openai-agents-python/mcp/) to learn more about the integration of the SDK with MCP.
346 
347Install the Python SDK.
348 
349```commandline
350pip install openai-agents
351```
352 
353Configure the OpenAI token:
354 
355```commandline
356export OPENAI_API_KEY="<openai_token>"
357```
358 
359And run the [application](./examples/cockroachdb_assistant.py).
360 
361```commandline
362python3 examples/cockroachdb_assistant.py
363```
364 
365You can troubleshoot your agent workflows using the [OpenAI dashboard](https://platform.openai.com/traces/).
366 
367### Augment
368 
369You can configure the CockroachDB MCP Server in Augment by importing the server via JSON:
370 
371```json
372{
373  "mcpServers": {
374    "CockroachDB MCP Server": {
375      "command": "uvx",
376      "args": [
377        "--from",
378        "git+https://github.com/cockroachdb/mcp-cockroachdb.git",
379        "cockroachdb-mcp-server",
380        "--url",
381        "postgresql://root@localhost:26257/defaultdb"
382      ]
383    }
384  }
385}
386```
387 
388### Claude Desktop
389 
390The simplest way to configure MCP clients is using `uvx`. Add the following JSON to your `claude_desktop_config.json`, remember to provide the full path to `uvx`.
391 
392```json
393{
394    "mcpServers": {
395        "cockroach-mcp-server": {
396            "type": "stdio",
397            "command": "/opt/homebrew/bin/uvx",
398            "args": [
399                "--from", "git+https://github.com/amineelkouhen/mcp-cockroachdb.git",
400                "cockroachdb-mcp-server",
401                "--url", "postgresql://localhost:26257/defaultdb"
402            ]
403        }
404    }
405}
406```
407 
408Please follow the prompt and give the details to configure the server and connect to CockroachDB (e.g., using a managed CockroachDB instance).
409The procedure will create the proper configuration in the `claude_desktop_config.json` configuration file.
410 
411### VS Code with GitHub Copilot
412 
413To use the CockroachDB MCP Server with VS Code, you must enable the [agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode) tools. Add the following to your `settings.json`:
414 
415```json
416{
417  "chat.agent.enabled": true
418}
419```
420 
421You can start the GitHub desired version of the CockroachDB MCP server using `uvx` by adding the following JSON to your `settings.json`:
422 
423```json
424"mcp": {
425    "servers": {
426        "CockroachDB MCP Server": {
427        "type": "stdio",
428        "command": "uvx", 
429        "args": [
430            "--from", "git+https://github.com/amineelkouhen/mcp-cockroachdb.git",
431            "cockroachdb-mcp-server",
432            "--url", "postgresql://root@localhost:26257/defaultdb"
433        ]
434        },
435    }
436},
437```
438 
439Alternatively, you can start the server using `uv` and configure your `mcp.json` or `settings.json`. This is usually desired for development.
440 
441```json
442{
443  "servers": {
444    "cockroach": {
445      "type": "stdio",
446      "command": "<full_path_uv_command>",
447      "args": [
448        "--directory",
449        "<your_mcp_server_directory>",
450        "run",
451        "src/main.py"
452      ],
453      "env": {
454        "CRDB_HOST": "<your_cockroachdb_hostname>",
455        "CRDB_PORT": "<your_cockroachdb_port>",
456        "CRDB_DATABASE": "<your_cockroach_database>",
457        "CRDB_USERNAME": "<your_cockroachdb_user>",
458        "CRDB_PWD": "<your_cockroachdb_password>"
459      }
460    }
461  }
462}
463```
464 
465For more information, see the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
466 
467### Cursor
468 
469Read the configuration options [here](#configuration-via-environment-variables) and input your selections with this link:
470 
471[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=cockroachdb&config=JTdCJTIyY29tbWFuZCUyMiUzQSUyMmRvY2tlciUyMHJ1biUyMC1pJTIwLS1ybSUyMC1lJTIwQ1JEQl9IT1NUJTIwLWUlMjBDUkRCX1BPUlQlMjAtZSUyMENSREJfREFUQUJBU0UlMjAtZSUyMENSREJfVVNFUk5BTUUlMjAtZSUyMENSREJfU1NMX01PREUlMjAtZSUyMENSREJfU1NMX0NBX1BBVEglMjAtZSUyMENSREJfU1NMX0tFWUZJTEUlMjAtZSUyMENSREJfU1NMX0NFUlRGSUxFJTIwLWUlMjBDUkRCX1BXRCUyMG1jcCUyRmNvY2tyb2FjaGRiJTIyJTJDJTIyZW52JTIyJTNBJTdCJTIyQ1JEQl9IT1NUJTIyJTNBJTIyMTI3LjAuMC4xJTIyJTJDJTIyQ1JEQl9QT1JUJTIyJTNBJTIyMjYyNTclMjIlMkMlMjJDUkRCX0RBVEFCQVNFJTIyJTNBJTIyZGVmYXVsdGRiJTIyJTJDJTIyQ1JEQl9VU0VSTkFNRSUyMiUzQSUyMnJvb3QlMjIlMkMlMjJDUkRCX1NTTF9NT0RFJTIyJTNBJTIyZGlzYWJsZSUyMiUyQyUyMkNSREJfU1NMX0NBX1BBVEglMjIlM0ElMjIlMjIlMkMlMjJDUkRCX1NTTF9LRVlGSUxFJTIyJTNBJTIyJTIyJTJDJTIyQ1JEQl9TU0xfQ0VSVEZJTEUlMjIlM0ElMjIlMjIlMkMlMjJDUkRCX1BXRCUyMiUzQSUyMiUyMiU3RCU3RA%3D%3D)
472 
473## Testing
474 
475You can use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) for visual debugging of this MCP Server.
476 
477```sh
478npx @modelcontextprotocol/inspector uv run src/main.py
479```
480 
481## Contributing
4821. Fork the repository
4832. Create a new branch (`feature-branch`)
4843. Commit your changes
4854. Push to your branch and submit a pull request.
486 
487## License
488This project is licensed under the **MIT License**.
489 
490## Quality Badge
491 
492<a href="https://glama.ai/mcp/servers/@amineelkouhen/mcp-cockroach">
493  <img width="380" height="200" src="https://glama.ai/mcp/servers/@amineelkouhen/mcp-cockroach/badge" />
494</a>
495 
496## Contact
497If you have any questions or need support, please feel free to contact us through [GitHub Issues](https://github.com/amineelkouhen/mcp-cockroachdb/issues).
498