云数据库-MCP

Name: 云数据库-MCP
Author: ydb-platform

作者：ydb-platform24 星标更新：2025-08-29

安装使用来源：spider==github.com

项目介绍

YDB MCP

模型上下文协议服务器用于YDB。它允许任何支持MCP的大型语言模型与YDB数据库进行交互。这种集成使AI驱动的数据库操作和自然语言交互成为可能。

使用方法

通过uvx

uvx是uv run tool的别名，允许在不明确安装的情况下运行各种Python应用程序。以下是使用uvx配置YDB MCP的示例。

示例：使用匿名认证

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local"
      ]
    }
  }
}

通过pipx

pipx允许在不明确安装每个应用的情况下从PyPI运行各种应用。但是，必须先安装。以下是使用pipx配置YDB MCP的示例。

示例：使用匿名认证

{
  "mcpServers": {
    "ydb": {
      "command": "pipx",
      "args": [
        "run", "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local"
      ]
    }
  }
}

通过pip

YDB MCP可以使用Python的包管理器 pip进行安装。该包在PyPI上可用，并包含所有必要的依赖项。

pip install ydb-mcp

要开始使用YDB MCP，您需要配置您的MCP客户端以与YDB实例通信。以下是一些示例配置文件，您可以根据自己的设置进行自定义，并将其放入MCP客户端的设置中。Python解释器的路径可能也需要调整到已安装ydb-mcp包的正确虚拟环境中。

示例：使用匿名认证

{
  "mcpServers": {
    "ydb": {
      "command": "python3",
      "args": [
        "-m", "ydb_mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local"
      ]
    }
  }
}

认证

无论使用哪种方法（uvx、pipx或pip），都可以为您的YDB安装配置认证。为此，请传递特殊的命令行参数。

使用用户名/密码认证

要使用用户名/密码认证，请指定--ydb-auth-mode、--ydb-login和--ydb-password参数：

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local",
        "--ydb-auth-mode", "login-password",
        "--ydb-login", "<your-username>",
        "--ydb-password", "<your-password>"
      ]
    }
  }
}

使用访问令牌认证

要使用访问令牌认证，请指定--ydb-auth-mode和--ydb-access-token参数：

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local",
        "--ydb-auth-mode", "access-token",
        "--ydb-access-token", "qwerty123"
      ]
    }
  }
}

使用服务账户认证

要使用服务账户认证，请指定--ydb-auth-mode和--ydb-sa-key-file参数：

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local",
        "--ydb-auth-mode", "service-account",
        "--ydb-sa-key-file", "~/sa_key.json"
      ]
    }
  }
}

可用工具

YDB MCP提供了以下工具来与YDB数据库进行交互：

ydb_query：对YDB数据库执行SQL查询
- 参数：
  - sql：要执行的SQL查询字符串
ydb_query_with_params：使用JSON参数执行参数化的SQL查询
- 参数：
  - sql：带有参数占位符的SQL查询字符串
  - params：包含参数值的JSON字符串
ydb_list_directory：列出YDB目录的内容
- 参数：
  - path：要列出的YDB目录路径
ydb_describe_path：获取关于YDB路径（表、目录等）的详细信息
- 参数：
  - path：要描述的YDB路径
ydb_status：获取当前YDB连接的状态

开发

该项目使用Make作为主要的开发工具，提供了一致的界面来处理常见的开发任务。

可用的Make命令

项目包括一个全面的Makefile，其中包含各种开发任务的命令。每个命令都旨在简化开发流程并确保代码质量：

make all：按顺序运行clean、lint和test（默认目标）
make clean：删除所有构建工件和临时文件
make test：使用pytest运行所有测试
- 可以通过环境变量进行配置：
  - LOG_LEVEL（默认：WARNING）- 控制测试输出的详细程度（DEBUG, INFO, WARNING, ERROR）
make unit-tests：仅运行单元测试并显示详细输出
- 可以通过环境变量进行配置：
  - LOG_LEVEL（默认：WARNING）- 控制测试输出的详细程度（DEBUG, INFO, WARNING, ERROR）
make integration-tests：仅运行集成测试并显示详细输出
- 可以通过环境变量进行配置：
  - YDB_ENDPOINT（默认：grpc://localhost:2136）
  - YDB_DATABASE（默认：/local）
  - MCP_HOST（默认：127.0.0.1）
  - MCP_PORT（默认：8989）
  - LOG_LEVEL（默认：WARNING）- 控制测试输出的详细程度（DEBUG, INFO, WARNING, ERROR）
make run-server：启动YDB MCP服务器
- 可以通过环境变量进行配置：
  - YDB_ENDPOINT（默认：grpc://localhost:2136）
  - YDB_DATABASE（默认：/local）
- 可以通过ARGS="your args"传递额外的参数
make lint：运行所有代码检查（flake8, mypy, black, isort）
make format：使用black和isort格式化代码
make install：以开发模式安装包
make dev：以开发模式安装包及其所有开发依赖项

测试输出详细程度控制

默认情况下，测试以最少的输出（WARNING级别）运行，以保持输出干净。您可以使用LOG_LEVEL环境变量控制测试输出的详细程度：

# 以调试输出运行所有测试
make test LOG_LEVEL=DEBUG

# 以信息输出运行集成测试
make integration-tests LOG_LEVEL=INFO

# 以警告输出运行单元测试（默认）
make unit-tests LOG_LEVEL=WARNING

可用的日志级别：

DEBUG：显示所有调试消息，对于详细的测试流程非常有用
INFO：显示信息性消息及以上的消息
WARNING：仅显示警告和错误（默认）
ERROR：仅显示错误消息