에이전트 강화
게시자가 제공하는 설치 방식입니다. PlugMCP 엔드포인트가 아닙니다.
원격 URL인가요, 내 컴퓨터에서 실행하는 명령인가요? 두 설치 방식의 차이
PlugMCP에서 실행
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
실행The 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.
--read-only mode, explicit confirm=True for destructive ops, redacted DSN responses.The CockroachDB MCP Server exposes CockroachDB as a set of MCP tools. Requests flow from any MCP client through a transport, into the safety layer, then to one of the thirteen tool categories, and finally to CockroachDB via an asyncpg connection pool.
flowchart LR
subgraph Clients["MCP Clients"]
direction TB
C1["Claude Desktop"]
C2["Cursor"]
C3["VS Code Copilot"]
C4["OpenAI Agents SDK"]
C5["Augment"]
end
subgraph Transport["Transport"]
direction TB
T1["stdio"]
T2["streamable HTTP"]
end
subgraph Server["CockroachDB MCP Server (FastMCP)"]
direction TB
subgraph Safety["Safety Layer"]
direction TB
S1["Identifier validation<br/>(strict regex)"]
S2["Parameterized values<br/>($1, $2, ...)"]
S3["--read-only gate"]
S4["--allow-destructive<br/>+ confirm=True"]
S5["DSN redaction"]
end
subgraph Tools["Tool Categories (13)"]
direction TB
subgraph Obs["Observe & Diagnose"]
O1["Cluster Monitoring"]
O2["Diagnostics"]
O3["Statistics"]
end
subgraph Data["Data & Schema"]
D1["Database Operations"]
D2["Table Management"]
D3["Query Engine"]
D4["Vector Search (C-SPANN)"]
end
subgraph Ops["Data Movement"]
P1["Job Management"]
P2["Backup & Restore"]
P3["Changefeeds (CDC)"]
end
subgraph Adm["Admin & Topology"]
A1["User & Privilege Management"]
A2["Multi-Region"]
A3["Cluster Admin"]
end
end
Pool["asyncpg connection pool"]
end
DB[("CockroachDB<br/>single- or multi-region cluster")]
Clients --> Transport
Transport --> Safety
Safety --> Tools
Tools --> Pool
Pool --> DB
The tools are organized into thirteen categories, grouped above by concern. Every write-shaped tool is gated by --read-only. Every destructive tool also requires --allow-destructive plus a per-call confirm=True parameter; see the Safety Model section.
Purpose: Provides tools for monitoring and managing CockroachDB clusters.
Summary:
Purpose: Handles database-level operations and connection management.
Summary:
Purpose: Provides tools for managing tables, indexes, views, schemas, and relationships in CockroachDB.
Summary:
alter_table_add_column, alter_table_drop_column, alter_table_rename_column.list_schemas, create_schema, drop_schema).Purpose: Executes and manages SQL queries and transactions.
Summary:
Purpose: Manage SQL users, roles, and privileges. Use this from an administrative agent to provision the agent's own scoped (non-root) user.
Summary:
list_users, create_user, drop_user, alter_user_password.create_role, drop_role, grant_role, revoke_role.show_grants, grant_privileges, revoke_privileges.Privileges are validated against an allowlist (SELECT, INSERT, UPDATE,
DELETE, ALL, BACKUP, RESTORE, MODIFYCLUSTERSETTING, ...). Identifiers
go through the same strict regex as everywhere else.
Purpose: Search VECTOR columns with CockroachDB's similarity operators (v25.2+) and manage C-SPANN ANN indexes.
Summary:
vector_similarity_search with metric of cosine (default), l2, ip,
or auto (matches the existing index opclass). Returns distance and a
derived similarity field.create_cspann_index with metric → opclass mapping
(vector_cosine_ops / vector_l2_ops / vector_ip_ops).drop_cspann_index (destructive).The query vector is always passed as a $1::VECTOR parameter; identifier and
optional where clause values are validated. For normalized embeddings (e.g.
Takara DS1, OpenAI text-embedding-3) all three metrics rank identically; the
default cosine is the safest because it ignores magnitude.
Purpose: Observe and control long-running CockroachDB jobs (BACKUP, RESTORE, IMPORT, SCHEMA CHANGE, CHANGEFEED).
Summary:
list_jobs (filter by status and type), get_job_status.pause_job, resume_job, cancel_job (destructive).Purpose: Take and restore cluster, database, and table backups.
Summary:
create_backup to s3/gs/azure/nodelocal/userfile destinations.list_backups to enumerate backups at a storage URI.restore_backup (destructive) with optional new_db_name.list_scheduled_backups.URI schemes are validated against an allowlist; identifier targets are identifier-validated.
Purpose: Compute and inspect the table statistics the cost-based optimizer relies on.
Summary:
create_statistics (CREATE STATISTICS).show_statistics (SHOW STATISTICS FOR TABLE).Purpose: Configure multi-region behaviour: regions, survival goals, table localities, zone configurations.
Summary:
show_regions, show_database_regions.add_database_region, drop_database_region (destructive).set_survival_goal (ZONE or REGION).set_table_locality (REGIONAL, REGIONAL_BY_ROW, REGIONAL_BY_TABLE, GLOBAL).show_zone_config for DATABASE/TABLE/INDEX.Purpose: Set up and operate CDC pipelines to Kafka, webhooks, or cloud storage.
Summary:
create_changefeed with sink-scheme validation (kafka, webhook-http(s), s3,
gs, azure-blob, external, null), JSON or Avro format, choice of envelope.list_changefeeds, pause_changefeed, resume_changefeed.cancel_changefeed (destructive).Purpose: Cluster-wide administration: cluster settings and node lifecycle.
Summary:
show_cluster_setting, set_cluster_setting, reset_cluster_setting
(destructive). Setting names are validated against a strict regex.decommission_node, drain_node. Note that SQL-initiated decommission
only marks intent; for the full lifecycle use the cockroach node CLI.Purpose: Inspect tracing spans and request statement-diagnostics bundles.
Summary:
get_recent_traces from crdb_internal.cluster_inflight_traces.list_statement_diagnostics_requests.request_statement_diagnostics for a statement fingerprint.The CockroachDB MCP Server supports the stdio transport and the streamable-http transport.
The 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:
uvx --from git+https://github.com/amineelkouhen/[email protected] cockroachdb-mcp-server --url postgresql://localhost:26257/defaultdb
Check the release notes for the latest version in the Releases section. Additional examples are provided below.
# Run with CockroachDB URI
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --url postgresql://localhost:26257/defaultdb
# Run with individual parameters
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --host localhost --port 26257 --database defaultdb --user root --password mypassword
# See all options
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --help
# Run with streamable HTTP transport
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
--url postgresql://localhost:26257/defaultdb \
--transport http \
--http-host 0.0.0.0 \
--http-port 8000 \
--http-path /mcp
For development or if you prefer to clone the repository:
# Clone the repository
git clone https://github.com/amineelkouhen/mcp-cockroachdb.git
cd mcp-cockroachdb
# Install dependencies using uv
uv venv
source .venv/bin/activate
uv sync
# Run with CLI interface
uv run cockroachdb-mcp-server --help
# Or run the main file directly (uses environment variables)
uv run src/main.py
Once 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. The following example is for Claude Desktop, but the same applies to any other MCP Client.
uv command full path (e.g. which uv)claude_desktop_config.json configuration file
- on a MacOS, at ~/Library/Application Support/Claude/{
"mcpServers": {
"cockroach": {
"command": "<full_path_uv_command>",
"args": [
"--directory",
"<your_mcp_server_directory>",
"run",
"src/main.py"
],
"env": {
"CRDB_HOST": "<your_cockroachdb_hostname>",
"CRDB_PORT": "<your_cockroachdb_port>",
"CRDB_DATABASE": "<your_cockroach_database>",
"CRDB_USERNAME": "<your_cockroachdb_user>",
"CRDB_PWD": "<your_cockroachdb_password>",
"CRDB_SSL_MODE": "disable|allow|prefer|require|verify-ca|verify-full",
"CRDB_SSL_CA_PATH": "<your_cockroachdb_ca_path>",
"CRDB_SSL_KEYFILE": "<your_cockroachdb_keyfile_path>",
"CRDB_SSL_CERTFILE": "<your_cockroachdb_certificate_path>",
}
}
}
}
You can troubleshoot problems by tailing the log file.
tail -f ~/Library/Logs/Claude/mcp-server-cockroach.log
For local development and testing, use the provided docker-compose.yaml to spin up both CockroachDB and the MCP server:
# Start CockroachDB and MCP server
docker compose up -d
# The MCP server is available at http://localhost:8000/mcp/
# CockroachDB UI is available at http://localhost:8080
# View logs
docker compose logs -f mcp-server
# Stop and clean up
docker compose down -v
You can use a dockerized deployment of this server. You can either build your image or use the official CockroachDB MCP Docker image.
If you'd like to build your image, the CockroachDB MCP Server provides a Dockerfile. Build this server's image with:
docker build -t mcp-cockroachdb .
Finally, 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:
{
"mcpServers": {
"cockroach": {
"command": "docker",
"args": ["run",
"--rm",
"--name",
"cockroachdb-mcp-server",
"-e", "CRDB_HOST=<cockroachdb_host>",
"-e", "CRDB_PORT=<cockroachdb_port>",
"-e", "CRDB_DATABASE=<cockroachdb_database>",
"-e", "CRDB_USERNAME=<cockroachdb_user>",
"mcp-cockroachdb"]
}
}
}
To use the CockroachDB MCP Docker image, just replace your image name (mcp-cockroachdb in the example above) with mcp/cockroachdb.
The repository ships an MCPB manifest under mcpb/manifest.json. MCPB (.mcpb) is a single-file archive that clients like Claude Desktop and catalogs like Smithery can install as a local stdio server, prompting the user for connection details via a UI instead of hand-editing JSON.
The manifest declares six user_config fields: url (marked sensitive, so the client stores it in the OS keychain rather than plaintext config), read_only (default true), allow_destructive (default false), and optional ssl_ca_cert / ssl_cert / ssl_key file pickers. Values are passed to the server via env vars (CRDB_URL, MCP_READ_ONLY, MCP_ALLOW_DESTRUCTIVE, CRDB_SSL_*).
Build the bundle:
npm install -g @anthropic-ai/mcpb
cp mcpb/manifest.json ./manifest.json
mcpb pack . cockroachdb-mcp-server.mcpb
Install locally in Claude Desktop: double-click the resulting .mcpb file. Claude Desktop will show the config form built from user_config.
Publish to Smithery:
smithery mcp publish ./cockroachdb-mcp-server.mcpb -n amineelkouhen/cockroachdb-mcp-server
The CockroachDB MCP Server can be configured in two ways: either via command-line arguments or via environment variables. The precedence is: CLI arguments > environment variables > default values.
When using the CLI interface, you can configure the server with command line arguments:
# Basic CockroachDB connection
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
--host localhost \
--port 26257 \
--db defaultdb \
--user root \
--password mypassword
# Using CockroachDB URI (simpler)
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
--url postgresql://root@localhost:26257/defaultdb
# SSL connection
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server \
--url postgresql://user:[email protected]:26257/defaultdb?sslmode=verify-full&sslrootcert=path/to/ca.crt&sslcert=path/to/client.username.crt&sslkey=path/to/client.username.key
# See all available options
uvx --from git+https://github.com/amineelkouhen/mcp-cockroachdb.git cockroachdb-mcp-server --help
Available CLI Options:
--url - CockroachDB connection URI (postgresql://user:pass@host:port/db)--host - CockroachDB hostname--port - CockroachDB port (default: 26257)--db - CockroachDB database name (default: defaultdb)--username - CockroachDB username (default: root)--password - CockroachDB password--ssl-mode - SSL mode - Possible values: disable (default), allow, prefer, require, verify-ca, verify-full--ssl-key - Path to SSL client key file--ssl-cert - Path to SSL client certificate file--ssl-ca-cert - Path to CA (root) certificate file--transport - MCP transport to use (stdio or http)--http-host - HTTP host to bind for streamable HTTP transport--http-port - HTTP port to bind for streamable HTTP transport--http-path - HTTP path for streamable HTTP transport (e.g., /mcp)--stateless-http - Enable stateless HTTP mode for horizontal scaling--use-env - Use environment variables for CockroachDB configuration--read-only - Refuse all DDL and write tools; recommended for assistant-style deployments--allow-destructive - Required for drop_database, drop_table, drop_index, drop_view. Even with this flag, every destructive call must include confirm=True.--version - Show the server version and exitThis server is designed for use with an LLM-driven agent, where a prompt-injection attack on the agent could turn into SQL injection or data destruction. Three layers of defense are built in:
^[A-Za-z_][A-Za-z0-9_]{0,62}$ before being interpolated into SQL.$1, $2, ...). No user-controlled value is interpolated into SQL.--read-only disables every DDL and write-shaped tool (drop_*, create_*, execute_query of INSERT/UPDATE/etc., bulk_import, ...).--allow-destructive is required for drop_* tools. Even then, the caller must pass confirm=True per call.connect() results.Recommended defaults for production assistant-style use: --read-only. For administrative agents that need to manage schema, set --allow-destructive but never disable the confirm=True requirement.
Logging is configured via environment variables:
MCP_LOG_LEVEL (default INFO) — standard Python logging level (DEBUG/INFO/WARNING/ERROR).MCP_LOG_JSON=1 — emit JSON-structured log lines, recommended when running with --transport http.CRDB_POOL_MIN (default 1)CRDB_POOL_MAX (default 10)CRDB_COMMAND_TIMEOUT (default 60 seconds)If desired, you can use environment variables. Defaults are provided for all variables.
There are several ways to set environment variables:
.env File:
Place 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).
For example, create a .env file with the following content from the .env.example file provided in the repository:cp .env.example .env
Then edit the .env file to set your CockroachDB configuration:
OR,
export CRDB_URL= postgresql://[email protected]:26257/defaultdb
This method is helpful for temporary overrides or quick testing.
Integrating 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.
Integrate this MCP Server with the OpenAI Agents SDK. Read the documents to learn more about the integration of the SDK with MCP.
Install the Python SDK.
pip install openai-agents
Configure the OpenAI token:
export OPENAI_API_KEY="<openai_token>"
And run the application.
python3 examples/cockroachdb_assistant.py
You can troubleshoot your agent workflows using the OpenAI dashboard.
You can configure the CockroachDB MCP Server in Augment by importing the server via JSON:
{
"mcpServers": {
"CockroachDB MCP Server": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/amineelkouhen/mcp-cockroachdb.git",
"cockroachdb-mcp-server",
"--url",
"postgresql://root@localhost:26257/defaultdb",
"--read-only"
]
}
}
}
The 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.
{
"mcpServers": {
"cockroach-mcp-server": {
"type": "stdio",
"command": "/opt/homebrew/bin/uvx",
"args": [
"--from", "git+https://github.com/amineelkouhen/mcp-cockroachdb.git",
"cockroachdb-mcp-server",
"--url", "postgresql://localhost:26257/defaultdb"
]
}
}
}
Please follow the prompt and give the details to configure the server and connect to CockroachDB (e.g., using a managed CockroachDB instance).
The procedure will create the proper configuration in the claude_desktop_config.json configuration file.
To use the CockroachDB MCP Server with VS Code, you must enable the agent mode tools. Add the following to your settings.json:
{
"chat.agent.enabled": true
}
You can start the GitHub desired version of the CockroachDB MCP server using uvx by adding the following JSON to your settings.json:
"mcp": {
"servers": {
"CockroachDB MCP Server": {
"type": "stdio",
"command": "uvx",
"args": [
"--from", "git+https://github.com/amineelkouhen/mcp-cockroachdb.git",
"cockroachdb-mcp-server",
"--url", "postgresql://root@localhost:26257/defaultdb"
]
},
}
},
Alternatively, you can start the server using uv and configure your mcp.json or settings.json. This is usually desired for development.
{
"servers": {
"cockroach": {
"type": "stdio",
"command": "<full_path_uv_command>",
"args": [
"--directory",
"<your_mcp_server_directory>",
"run",
"src/main.py"
],
"env": {
"CRDB_HOST": "<your_cockroachdb_hostname>",
"CRDB_PORT": "<your_cockroachdb_port>",
"CRDB_DATABASE": "<your_cockroach_database>",
"CRDB_USERNAME": "<your_cockroachdb_user>",
"CRDB_PWD": "<your_cockroachdb_password>"
}
}
}
}
For more information, see the VS Code documentation.
Read the configuration options here and input your selections with this link:
The repository ships with a pytest suite covering the SQL identifier validators, type serializers, DSN parsing, URL helpers, output formatting, and policy gating (read-only mode, destructive-op gating, injection rejection).
uv sync --extra dev
uv run pytest -v
CI runs the same suite on Python 3.12 and 3.13. See .github/workflows/test.yml.
uv run ruff check src tests
uv run ruff format --check src tests
For interactive debugging of the live server, use the MCP Inspector:
npx @modelcontextprotocol/inspector uv run src/main.py
feature-branch)This project is licensed under the MIT License.
If you have any questions or need support, please feel free to contact us through GitHub Issues.
The CockroachDB MCP Server is a natural language interface designed for agentic applications to manage, monitor and query data in CockroachDB.
도구
아직 도구 목록이 없습니다. 원격 서버는 첫 상태 확인 후에 도구 목록이 생깁니다.
FAQ
이 페이지에서 Cursor, Claude Desktop, Claude Code 또는 VS Code용 stdio 설정을 복사합니다. PlugMCP 프록시가 아니라 게시자의 설치 방식을 사용합니다.
이 레코드에는 필수 환경 변수가 등록되어 있지 않습니다.
MCP Cockroachdb은(는) stdio를 통해 로컬에서 실행됩니다.
마지막 확인: 2026-10-28. The CockroachDB MCP Server is a natural language interface designed for agentic applications to manage, monitor and query data in CockroachDB.