内容
<p align="center">
<img src='docs/media/cockroachdb.png?raw=true' alt='CockroachDB' width='70%'>
</p>
# CockroachDB MCP 服务器
[](https://github.com/cockroachdb/cockroachdb-mcp-server/actions/workflows/ci.yaml)
[](https://github.com/cockroachdb/cockroachdb-mcp-server/releases)
[](https://pkg.go.dev/github.com/cockroachdb/cockroachdb-mcp-server)
[](go.mod)
[](LICENSE)
CockroachDB MCP 服务器是一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器， 将 CockroachDB 暴露给 AI 代理，作为一组类型化的工具。 默认情况下提供读取工具；写入和 DDL 工具通过环境变量开启。
- [安装](#安装)
- [设置 - MCP 客户端配置](#设置---mcp-客户端配置)
- [配置](#配置)
- [工具](#工具)
- [测试](#测试)
- [贡献](#贡献)
- [安全](#安全)
- [许可证](#许可证)
## 安装
需要 Go 1.26+ 和可访问的 CockroachDB 集群。
```bash
go install github.com/cockroachdb/cockroachdb-mcp-server@latest
```
二进制文件位于 `$(go env GOPATH)/bin/cockroachdb-mcp-server`。
### 预编译二进制文件
从 [发布](https://github.com/cockroachdb/cockroachdb-mcp-server/releases) 页面获取 `linux/{amd64,arm64}` 或 `windows/{amd64,arm64}` 的 tarball， 从第一个发布版本开始提供。
### Docker
多架构镜像（`linux/amd64`，`linux/arm64`）发布到 Google Artifact Registry， 每次发布都会更新：
```bash
docker pull us-docker.pkg.dev/releases-prod/cockroachdb-mcp-server/cockroachdb-mcp-server:<版本>
```
用发布的 [发布页面](https://github.com/cockroachdb/cockroachdb-mcp-server/releases) 上的版本替换 `<版本>`， 或直接列出可用的镜像标签：
```bash
gcloud artifacts docker tags list us-docker.pkg.dev/releases-prod/cockroachdb-mcp-server/cockroachdb-mcp-server
```
镜像在 [distroless](https://github.com/GoogleContainerTools/distroless) 上以 `nonroot` 用户运行。 Apple Silicon 上的 macOS 用户可以通过 Docker 原生运行 `linux/arm64` 镜像。
### 从源代码构建
```bash
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
```
macOS: 使用 `go install` 或从源代码构建。 预编译二进制文件不包括 darwin， 因为 CockroachDB 解析器依赖项在 macOS 上需要 cgo。
## 设置 - MCP 客户端配置
将以下内容之一放入 MCP 客户端的配置中（Claude Desktop、Cursor、 VS Code、Copilot CLI 等）。 每个客户端读取一个 `mcpServers` 块或其等效配置； 请参阅客户端文档以获取文件位置。
> GUI 客户端（例如 Claude Desktop）通常会以最小的 PATH 启动， 并且不会扩展 `~`， 因此一个单独的 `command` 可能无法解析； 使用绝对二进制路径代替， 例如 `/Users/<username>/go/bin/cockroachdb-mcp-server`。
### 标准输入输出 + 基于证书的身份验证（推荐）
```json
{
"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"
}
}
}
}
```
### 标准输入输出 + 完整连接字符串
```json
{
"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"
}
}
}
}
```
### 标准输入输出 + 本地不安全集群（仅限开发，启用写入）
对于本地 `cockroach start-single-node --insecure` 或 `cockroach demo --insecure` 集群， 开启无 TLS 连接； 不需要证书文件：
```json
{
"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"
}
}
}
}
```
### HTTPS（共享/远程部署）
将服务器作为长期运行的进程运行， 然后将 MCP 客户端指向带有 bearer token 的 URL：
```bash
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
```
将 `CRDB_MCP_HTTP_LISTEN_ADDR` 设置为适合您部署的 `host:port`， 例如 `127.0.0.1:9090` 以仅服务本地流量， 并使用 TLS 终止反向代理（带有 `CRDB_MCP_ALLOW_INSECURE_HTTP=true`）， 或 `10.0.0.5:8443` 以绑定特定接口。
然后将 MCP 客户端指向服务器：
```json
{
"mcpServers": {
"cockroachdb": {
"type": "http",
"url": "https://mcp.example.com:8443",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
```
> HTTP 模式默认启用 TLS。 如果没有 `CRDB_MCP_TLS_CERT` 和 `CRDB_MCP_TLS_KEY`， 则拒绝启动， 除非 `CRDB_MCP_ALLOW_INSECURE_HTTP=true`（适用于 TLS 终止反向代理后的部署）。 `/healthz` 和 `/ready` 是未经身份验证的 `GET`/`HEAD` 探测； 所有其他路径都需要 bearer token。
## 配置
所有配置均通过环境变量进行。
### 身份验证
**标准输入输出模式：** 服务器作为 AI 代理主机的子进程运行。 推荐基于证书的身份验证。 服务器可以从其进程环境中读取 `CRDB_PWD`， 一个嵌入在 `CRDB_DATABASE_URL`、 `PGPASSWORD` 或 `~/.pgpass` 中的密码。 为了保护这些凭证， 默认情况下基于密码的身份验证被拒绝。 设置 `CRDB_MCP_ALLOW_PASSWORD_AUTH=true` 以选择加入。
**HTTP 模式：** 客户端通过 bearer token（`CRDB_MCP_BEARER_TOKEN`）向 MCP 服务器进行身份验证 - 请参阅 [HTTPS 设置](#https-共享-远程部署) 以获取 token 生成。 默认情况下需要 TLS； 清除文本 HTTP 需要 `CRDB_MCP_ALLOW_INSECURE_HTTP=true`（适用于 TLS 终止反向代理后的部署）。 负责上游身份验证的组织（反向代理，网关，mTLS）可以设置 `CRDB_MCP_ALLOW_NO_BEARER=true` 以跳过强制执行 bearer。
`CRDB_DATABASE_URL`（一个完整的 libpq 连接字符串）优先于以下分割变量。 在两种身份验证模式中，`sslmode` 必须是 `require`、`verify-ca` 或 `verify-full`； 如果 `CRDB_DATABASE_URL` 省略 `sslmode`， 则在启动时拒绝， 而可选的 TLS 模式（`disable`、`allow`、`prefer`）需要 `CRDB_MCP_ALLOW_INSECURE_DB=true`。
| 变量 | 目的 | 默认值 |
| --- | --- | --- |
| `CRDB_HOST` | 主机名 | 必需 |
| `CRDB_PORT` | 端口 | `26257` |
| `CRDB_USERNAME` | SQL 用户 | 必需 |
| `CRDB_PWD` | 密码（不鼓励，参见上面的注释） | - |
| `CRDB_SSL_MODE` | `require`、`verify-ca` 或 `verify-full`； `disable`、`allow`、`prefer` 搭配 `CRDB_MCP_ALLOW_INSECURE_DB=true` | `verify-full` |
| `CRDB_SSL_CA_PATH` | CA 证书路径（`verify-ca` / `verify-full` 需要） | - |
| `CRDB_SSL_CERTFILE` | 客户端证书路径 | 必需 |
| `CRDB_SSL_KEYFILE` | 客户端密钥路径 | 必需 |
### 查询行为
| 变量 | 目的 | 默认值 |
| --- | --- | --- |
| `CRDB_MCP_QUERY_TIMEOUT` | 查询超时（Go 时长，例如 `30s`） | `30s` |
| `CRDB_MCP_MAX_ROWS_COUNT` | CRDB 发出的最大 LIMIT 列表样式工具上限 | `10000` |
| `CRDB_MCP_MAX_CONNS` | pgxpool 连接计数的上限（≤ 100） | `10` |
| `CRDB_MCP_TXN_QOS` | 默认事务 QoS：`background`、`regular` 或 `critical` | `background` |
| `CRDB_MCP_ENABLE_WRITE_QUERIES` | 写入工具的门控（`create_database`、`create_table`、`insert_rows`、`update_rows`、`delete_rows`） | `false` |
| `CRDB_MCP_ALLOW_PASSWORD_AUTH` | 选择基于密码的身份验证 | `false` |
| `CRDB_MCP_ALLOW_INSECURE_DB` | 选择允许 sslmode 值为 `disable`、`allow`、`prefer`， 无需 TLS。 仅限开发 | `false` |
MCP 流量默认运行在 `default_transaction_quality_of_service=background`， 因此它不会与延迟敏感的前台工作负载竞争。 选取值的优先级：
1. 如果设置了 `CRDB_MCP_TXN_QOS`（`background`、`regular` 或 `critical`）。
2. 否则，`CRDB_DATABASE_URL` 中的 `default_transaction_quality_of_service=...` 查询参数（如果存在）。
3. 否则，`background`。
### 传输
| 变量 | 目的 | 默认值 |
| --- | --- | --- |
| `CRDB_MCP_TRANSPORT` | `stdio` 或 `http` | `stdio` |
| `CRDB_MCP_HTTP_LISTEN_ADDR` | HTTP 模式下的监听地址，任意 `host:port`。 省略主机以绑定所有接口。 示例：`:8080`、`0.0.0.0:8443`、`127.0.0.1:9090` | `:8080` |
| `CRDB_MCP_BEARER_TOKEN` | 客户端必须在 `Authorization: Bearer <token>` 中发送的 bearer token。 HTTP 模式下必需，除非 `CRDB_MCP_ALLOW_NO_BEARER=true`； 必须至少 16 个字符 | - |
| `CRDB_MCP_TLS_CERT` | PEM 编码的服务器证书路径。 HTTPS 需要，除非 `CRDB_MCP_ALLOW_INSECURE_HTTP=true` | - |
| `CRDB_MCP_TLS_KEY` | PEM 编码的私钥路径。 HTTPS 需要，除非 `CRDB_MCP_ALLOW_INSECURE_HTTP=true` | - |
| `CRDB_MCP_ALLOW_INSECURE_HTTP` | 选择纯文本 HTTP（适用于反向代理部署） | `false` |
| `CRDB_MCP_ALLOW_NO_BEARER` | 选择跳过 bearer 身份验证（适用于上游身份验证部署）。 记录启动警告 | `false` |
### 日志记录
| 变量 | 目的 | 默认值 |
| --- | --- | --- |
| `CRDB_MCP_LOG_LEVEL` | `debug`、`info`、`warn`、`error` | `info` |
| `CRDB_MCP_LOG_PATH` | 日志文件路径，或 `-` 表示 stderr。 无轮换； 使用 logrotate 或您的编排器 | - |
### 跟踪（OpenTelemetry）
跟踪是可选的： 如果未设置以下变量，则不会安装导出器。 启用后， 工具调用及其 SQL 语句将作为跨度导出， 而服务器日志将作为 OTel 日志记录。 查询文本和错误在导出前会被删除， 因此字面值和用户数据永远不会离开服务器。
| 变量 | 目的 | 默认值 |
| --- | --- | --- |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP gRPC 端点； 标准的 `OTEL_*` 环境变量将被忽略 | - |
| `CRDB_MCP_OTEL_FILE` | 将跟踪和日志写入此文件作为 JSON 行（优先级更高） | - |
在 stdio 模式下， 将变量添加到您的 [MCP 客户端配置](#设置---mcp-客户端配置) 的 `env` 块中； 在 HTTP 模式下， 在服务器的环境中导出：
```json
{
"env": {
"CRDB_DATABASE_URL": "postgresql://...",
"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317"
}
}
```
## 工具
授予连接的 SQL 角色仅所需的权限。 避免管理员和写入权限， 除非显式注册写入工具； 有关角色配方， 请参阅 [安全](#安全)。
`CRDB_MCP_ENABLE_WRITE_QUERIES` 启用所有写入工具。 对于逐操作控制， 仅授予连接角色所需的 SQL 权限， 例如 `SELECT`、`INSERT` 和 `UPDATE` 但不包括 `DELETE`， 以允许在没有删除的情况下写入。
### 只读（默认注册）
| 工具 | 描述 |
| --- | --- |
| `list_databases` | 列出所有数据库。 可选 `limit`（默认 100，最大 10000）和 `offset`。 |
| `list_tables` | 列出数据库中的表。 必需：`database`。 可选：`limit`、`offset`。 |
| `get_table_schema` | 返回表的 `CREATE TABLE`。 必需：`database`、`table`。 可选：`schema`（默认 `public`）。 |
| `get_cluster` | 集群身份和版本元数据：cluster_id、cluster_name、binary_version。 身份字段需要 `crdb_internal` 访问权限（默认情况下在 v25.4+ 上受限）； 当不可用时， 它们为空， 原因在 `unavailable` 下。 |
| `list_sql_users` | 集群中的 SQL 用户。 可选：`limit`、`offset`。 |
| `list_cluster_nodes` | 集群节点， 包含地址、存活状态、位置。 需要 admin 或 `VIEWCLUSTERMETADATA`。 |
| `show_running_queries` | 当前执行的语句， 按启动时间降序排列。 可选：`limit`、`offset`。 |
| `select_query` | 执行 SELECT 语句。 如果未提供， 则追加默认 LIMIT 100； 上限为 `CRDB_MCP_MAX_ROWS_COUNT`。 |
| `explain_query` | 返回语句的 EXPLAIN 计划， 而不执行它。 拒绝 `EXPLAIN ANALYZE`（和 `EXPLAIN ANALYZE (DEBUG)`）。 显示选项（`VERBOSE`、`DISTSQL`、`TYPES`、`OPT`等）传递。 |
| `show_statement` | 执行 SHOW 语句， 例如 `SHOW SCHEMAS`、`SHOW INDEXES`、`SHOW REGIONS`、`SHOW JOBS`。 可选：`limit`、`offset`。 |
### 写入（需要 `CRDB_MCP_ENABLE_WRITE_QUERIES=true`）
| 工具 | 描述 |
| --- | --- |
| `create_database` | 创建数据库。 必需：`name`。 |
| `create_table` | 执行单个 `CREATE TABLE` 语句。 必需：`statement`。 |
| `insert_rows` | 执行单个 `INSERT` 语句； 返回受影响的行。 必需：`statement`。 |
| `update_rows` | 执行单个 `UPDATE` 语句； 强制 `WHERE` 子句。 返回受影响的行。 必需：`statement`。 |
| `delete_rows` | 执行单个 `DELETE` 语句； 强制 `WHERE` 子句。 返回受影响的行。 必需：`statement`。 |
任何包含 `RETURNING` 子句的写入工具都返回受影响的行， 而不仅仅是计数。
## 测试
```bash
go test ./...
```
通过 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 进行交互式检查：
```bash
npm install -g @modelcontextprotocol/inspector
mcp-inspector cockroachdb-mcp-server
```
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 安全
请通过 [SECURITY.md](SECURITY.md) 报告漏洞。
### 安全模型
服务器验证语句形状（每次调用单个语句，`UPDATE` 和 `DELETE` 需要强制 `WHERE` 子句）， 但不限制语句可以针对哪些数据库、模式或表。 每个工具调用都具有连接 SQL 角色的完全权限：角色， 而不是服务器， 是安全边界。
连接为专用角色， 限定为智能体所需的内容， 永远不要作为 `root` 或 `admin` 成员； 参见
[`CREATE ROLE`](https://www.cockroachlabs.com/docs/stable/create-role)，
[`GRANT`](https://www.cockroachlabs.com/docs/stable/grant) 和
[授权概述](https://www.cockroachlabs.com/docs/stable/security-reference/authorization)。
授予 `SELECT` 权限， 仅在表上启用写模式， 并在集群内省工具需要时授予 `GRANT SYSTEM VIEWACTIVITYREDACTED,VIEWCLUSTERMETADATA`。
注意， 服务器无法区分操作员预期的工具调用和智能体读取的被攻击者控制的内容（提示注入）； 上述角色范围是针对后者的隔离。
## 许可证
[Apache License 2.0](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器