YugabyteDB MCP Server

YugabyteDB MCP服务器

一 主控程序 YugabyteDB的服务器实现，允许LLM直接与您的数据库交互。

特性

• 列出数据库中的所有表，包括架构和行数
• 运行只读SQL查询并以JSON格式返回结果
• 设计用于 快速MCP 与Claude Desktop、Cursor和Windsurf Editor等MCP客户端兼容

先决条件

• Python 3.10或更高版本
• 紫外线 已安装以管理和运行服务器
• 正在运行的YugabyteDB数据库

安装

克隆此存储库并安装依赖项：

git clone git@github.com:yugabyte/yugabytedb-mcp-server.git
cd yugabytedb-mcp-server
uv sync

配置

服务器配置如下：

用法

运行服务器

您可以使用以下命令运行服务器 STDIO 使用紫外线运输：

uv run src/server.py

或具有状态 Streamable-HTTP 运输：

uv run src/server.py --transport http

或无国籍 Streamable-HTTP 运输：

uv run src/server.py --transport http --stateless-http

使用Docker运行服务器

构建Docker镜像：

docker build -t mcp/yugabytedb .

用以下方式运行容器 STDIO 运输：

docker run -p 8000:8000 -e YUGABYTEDB_URL="your-db-url" mcp/yugabytedb

或与 Streamable-HTTP 运输：

状态服务器：

docker run -p 8000:8000 \
  -e YUGABYTEDB_URL="your-db-url" \
  mcp/yugabytedb --transport=http

无状态服务器：

docker run -p 8000:8000 \
  -e YUGABYTEDB_URL="your-db-url" \
  -e YB_MCP_TRANSPORT=http \
  -e YB_MCP_STATELESS_HTTP=true \
  mcp/yugabytedb

启用SSL群集的无状态服务器：

docker run -p 8000:8000 \
  -v /path/to/root.crt:/certs/root.crt:ro \
  -e YUGABYTEDB_URL="your-db-url" \
  mcp/yugabytedb \
  --transport=http \
  --stateless-http

使用AWS Secrets Manager的TLS证书运行

如果您的YugabyteDB集群启用了TLS，并且其根证书存储在AWS Secrets Manager中，则MCP服务器可以自动获取和配置它。

明文秘密（PEM直接存储）

机密值包含PEM证书本身。

docker run -p 8000:8000 \
  -e YUGABYTEDB_URL="host=... port=5433 dbname=... user=... password=... sslmode=verify-full" \
  -e YB_MCP_TRANSPORT=http \
  -e YB_MCP_STATELESS_HTTP=true \
  -e YB_AWS_SSL_ROOT_CERT_SECRET_ARN=arn:ofthe:secret:manager \
  -e YB_AWS_SSL_ROOT_CERT_SECRET_REGION=region-of-the-secret-manager \
  -e AWS_ACCESS_KEY_ID="XXX" \
  -e AWS_SECRET_ACCESS_KEY="XXX" \
  -e AWS_SESSION_TOKEN="XXX" \
  mcp/yugabytedb

JSON密钥（一个密钥中包含多个证书）

秘密值是JSON，例如：

{
  "cert-cluster-1": "-----BEGIN CERTIFICATE----- ...",
  "cert-cluster-2": "-----BEGIN CERTIFICATE----- ..."
}

选择要使用的证书：

docker run -p 8000:8000 \
  -e YUGABYTEDB_URL="host=... port=5433 dbname=... user=... password=... sslmode=verify-full" \
  -e YB_MCP_TRANSPORT=http \
  -e YB_MCP_STATELESS_HTTP=true \
  -e YB_AWS_SSL_ROOT_CERT_SECRET_ARN=arn:ofthe:secret:manager \
  -e YB_AWS_SSL_ROOT_CERT_KEY=cert-cluster-1 \
  -e YB_AWS_SSL_ROOT_CERT_SECRET_REGION=region-of-the-secret-manager \
  -e AWS_ACCESS_KEY_ID="XXX" \
  -e AWS_SECRET_ACCESS_KEY="XXX" \
  -e AWS_SESSION_TOKEN="XXX" \
  mcp/yugabytedb

默认情况下，证书被写入/tmp/yb-root.crt。 您可以使用以下命令覆盖此内容：

-e YB_SSL_ROOT_CERT_PATH=/custom/path/root.crt

MCP客户端配置

要将此服务器与MCP客户端（例如，Claude Desktop、Cursor）一起使用，请将其添加到MCP客户端配置中。

跑步通过 uv

游标配置示例：

{
  "mcpServers": {
    "yugabytedb-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/cloned/yugabytedb-mcp-server/",
        "run",
        "src/server.py"
      ],
      "env": {
        "YUGABYTEDB_URL": "dbname=database_name host=hostname port=5433 user=username password=password load_balance=true topology_keys=cloud.region.zone1,cloud.region.zone2"
      }
    }
  }
}

• 替换 /path/to/cloned/yugabytedb-mcp-server/ 带有克隆存储库的路径。
• 在中设置正确的数据库URL env 部分。

通过Docker运行（例如，在Claude中）

构建docker容器后，添加以下内容 claude_config.json 其他编辑器的条目或等效json文件：

{
  "mcpServers": {
    "yugabytedb-mcp-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "YUGABYTEDB_URL=dbname=yugabyte host=host.docker.internal port=5433 user=yugabyte password=yugabyte load_balance=false",
        "mcp/yugabytedb"
      ]
    }
  }
}

克劳德桌面版

1. 编辑配置文件。转到克劳德->设置->开发人员->编辑配置
2. 在下面添加上述配置 mcpServers.
3. 重新启动克劳德桌面。

克劳德桌面日志

Claude Desktop的日志可以在以下位置找到：

• MacOS:~/库/日志/克劳德
• Windows：%APPDATA%\\Claude\\Logs

这些日志可用于诊断连接问题或MCP服务器配置的其他问题。有关更多详细信息，请参阅 官方文件.

光标

1. 安装 光标 在你的机器上。
2. 转到光标>设置>光标设置>MCP>添加新的全局MCP服务器。
3. 添加上述配置。
4. 保存配置。
5. 您将在mcp服务器列表中看到yugabytedb-mcp服务器作为添加的服务器。刷新以查看服务器是否已启用。

游标日志

在Cursor的底部面板中，单击“输出”，然后从下拉菜单中选择“Cursor MCP”以查看服务器日志。这可以帮助诊断连接问题或MCP服务器配置的其他问题。

Windsurf编辑器

1. 安装 Windsurf编辑器 在你的机器上。
2. 前往Windsurf>设置>Windsurf设置>级联>模型上下文协议（MCP）服务器>添加服务器>添加自定义服务器。
3. 添加上述配置。
4. 保存并刷新。

带MCP检查器的流式HTTP

1. 使用Streamable HTTP启动服务器：

   uv run src/server.py --transport http

或者使用Docker：

   docker run -p 8000:8000 -e YUGABYTEDB_URL="..." mcp/yugabytedb --transport=http

1. 启动检查器：

   npx @modelcontextprotocol/inspector

1. 在GUI中，使用URL：

   http://localhost:8000/mcp

- 将运输类型更改为 Streamable-HTTP - 从终端输出中添加代理令牌

提供的工具

• 汇总数据库：列出数据库中的所有表，包括架构和行数。
• run_read_only_query：运行只读SQL查询并以JSON格式返回结果。

示例用法

通过MCP客户端连接后，您可以：

• 要求提供数据库表和模式的摘要
• 运行SELECT查询并获取JSON格式的结果

环境变量

• YUGABYTEDB_URL：（必填）YugabyteDB/PostgreSQL数据库的连接字符串

故障排除

• 确保 YUGABYTEDB_URL 设置正确
• 验证您的数据库是否正在运行且可访问
• 检查您的用户是否具有必要的权限
• 确保 uv 已安装并在PATH中可用。注意：如果claude无法访问uv，则显示错误： spawn uv ENOENT，尝试将uv符号链接以实现全局访问：

sudo ln -s "$(which uv)" /usr/local/bin/uv

• 查看MCP客户端中的日志，查看是否存在连接或查询错误

发展

• 项目依赖关系在中管理 pyproject.toml
• 主服务器逻辑在 src/server.py