星战科技xingzhan.cloud
返回市场
YugabyteDB-MCP-服务器

YugabyteDB-MCP-服务器

作者：yugabyte8 星标更新：2025-08-05
安装使用来源：spider==github.com

项目介绍

YugabyteDB MCP Server

用于YugabyteDB的MCP服务器实现，允许大型语言模型直接与您的数据库交互。

功能

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

预备条件

安装

克隆此仓库并安装依赖项：

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

配置

服务器通过以下环境变量进行配置：

  • YUGABYTEDB_URL: 您的YugabyteDB数据库连接字符串（例如，dbname=database_name host=hostname port=5433 user=username password=password）

示例.env文件：

YUGABYTEDB_URL=postgresql://user:password@localhost:5433/yugabyte

使用

运行服务器

您可以使用STDIO传输方式运行服务器：

uv run src/server.py

或者使用Streamable-HTTP传输方式：

uv run src/server.py --transport http

使用Docker运行服务器

构建Docker镜像：

docker build -t mcp/yugabytedb .

使用STDIO传输方式运行容器：

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

或者使用Streamable-HTTP传输方式：

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

MCP客户端配置

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

通过uv运行

Cursor的示例配置：

{
  "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/替换为您克隆的仓库路径。
  • 在env部分设置正确的数据库URL。

通过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"
      ]
    }
  }
}

Claude Desktop

  1. 编辑配置文件。前往Claude -> 设置 -> 开发者 -> 编辑配置
  2. 在mcpServers下添加上述配置。
  3. 重启Claude Desktop。

Claude Desktop日志

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

  • MacOS: ~/Library/Logs/Claude
  • Windows: %APPDATA%\Claude\Logs

这些日志可用于诊断连接问题或其他MCP服务器配置问题。更多详情，请参阅官方文档。

Cursor

  1. 在您的机器上安装Cursor。
  2. 前往Cursor > 设置 > Cursor设置 > MCP > 添加一个新的全局MCP服务器。
  3. 添加上述配置。
  4. 保存配置。
  5. 您将在MCP服务器列表中看到已添加的yugabytedb-mcp-server。刷新以查看服务器是否启用。

Cursor日志

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

Windsurf Editor

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

使用Streamable-HTTP与MCP Inspector

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

    uv run src/server.py --transport http

    或者使用Docker：

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

  2. 启动检查器：

    npx @modelcontextprotocol/inspector

  3. 在GUI中使用URL：

    http://localhost:8080/invocations/mcp
    • 更改传输类型为Streamable-HTTP
    • 添加来自终端输出的代理令牌

提供的工具

  • summarize_database: 列出数据库中的所有表，包括模式和行数。
  • 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中