Skip to main content
Glama
deenesjakoruzh
ydb-platform

YDB MCP

Official
by ydb-platform
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

YDB MCP

License PyPI version

Model Context Protocol 服务器，适用于 YDB。它允许任何支持 MCP 的 LLM 与 YDB 数据库进行交互。此集成支持 AI 驱动的数据库操作，并允许与您的 YDB 实例进行自然语言交互。

使用方法

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

Related MCP server: MCP MySQL Server

可用工具

YDB MCP 提供以下工具用于与 YDB 数据库交互：

  • ydb_query：对 YDB 数据库运行 SQL 查询

    • 参数：

      • sql：要执行的 SQL 查询字符串

  • ydb_query_with_params：运行带有 JSON 参数的参数化 SQL 查询

    • 参数：

      • sql：带有参数占位符的 SQL 查询字符串

      • params：包含参数值的 JSON 字符串

  • ydb_explain_query：解释 SQL 查询（返回执行计划）

    • 参数：

      • sql：要解释的 SQL 查询字符串

  • ydb_explain_query_with_params：解释参数化 SQL 查询

    • 参数：

      • sql：带有参数占位符的 SQL 查询字符串

      • params：包含参数值的 JSON 字符串

  • ydb_list_directory：列出 YDB 中的目录内容

    • 参数：

      • path：要列出的 YDB 目录路径

  • ydb_describe_path：获取有关 YDB 路径（表、目录等）的详细信息

    • 参数：

      • path：要描述的 YDB 路径

  • ydb_status：获取 YDB 连接的当前状态

构建自定义 MCP 服务器

YDBMCPServer 设计为可被继承。您可以在已建立的 YDB 连接之上添加自己的工具，并可选择禁用内置的通用工具，仅公开应用程序所需的查询。

为什么要构建自定义服务器？

  • 安全性 — 将 LLM 限制为一组固定的只读查询，而不是公开任意 SQL 执行。

  • 领域特定性 — 为模型提供符合您业务逻辑的工具，而不是原始数据库原语。

  • 简洁性 — 更少的工具意味着模型更少的歧义。

可用方法

在您的子类中重写或调用这些方法：

方法

描述

await self.execute(sql, params=None)

运行 SQL 查询。返回 list[dict]，每个字典包含 "columns" 和 "rows"。

await self.explain(sql, params=None)

将查询执行计划作为 dict 返回。

await self.list_directory(path)

列出 YDB 目录。返回包含 "path" 和 "items" 的 dict。

await self.describe_path(path)

描述 YDB 路径（表结构、目录等）。返回一个 dict。

params 参数是一个普通的 dict。没有 $ 前缀的键会自动添加该前缀。要指定显式的 YDB 类型，请使用 (value, "TypeName") 元组 — 例如 {"id": (42, "Int64")}。

控制通用工具

使用 generic_tools 类属性来控制注册哪些内置工具：

值

效果

set(YDBGenericTool)

所有内置工具（默认）

set()

无内置工具 — 仅限您自己的工具

{YDBGenericTool.QUERY, YDBGenericTool.STATUS}

仅列出的工具

YDBGenericTool 是一个字符串枚举 — 可用值：QUERY、QUERY_WITH_PARAMS、EXPLAIN、EXPLAIN_WITH_PARAMS、STATUS、LIST_DIRECTORY、DESCRIBE_PATH。

示例

# my_server.py
from ydb_mcp import YDBMCPServer, YDBGenericTool, serialize_ydb_response


class OrdersServer(YDBMCPServer):
    """Minimal read-only MCP server for the orders service."""

    generic_tools = {YDBGenericTool.STATUS}  # keep status check for diagnostics

    def __init__(self, **kwargs):
        super().__init__(**kwargs)

        @self.tool()
        async def get_order(order_id: str) -> str:
            """Fetch a single order by ID."""
            rows = await self.execute(
                "SELECT * FROM orders WHERE id = $id",
                {"id": order_id},
            )
            return serialize_ydb_response(rows)

        @self.tool()
        async def list_recent_orders(limit: int = 10) -> str:
            """Return the most recent orders."""
            rows = await self.execute(
                "SELECT * FROM orders ORDER BY created_at DESC LIMIT $limit",
                {"limit": limit},
            )
            return serialize_ydb_response(rows)


if __name__ == "__main__":
    OrdersServer(
        endpoint="grpc://localhost:2136",
        database="/local",
    ).run()

直接运行它：

python my_server.py

或者在您的客户端配置中将其连接为 MCP 服务器：

{
  "mcpServers": {
    "orders": {
      "command": "python",
      "args": ["my_server.py"]
    }
  }
}

开发

该项目使用 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：运行所有 lint 检查（flake8、mypy、black、isort）

  • make format：使用 black 和 isort 格式化代码

  • make install：以开发模式安装包

  • make dev：以开发模式安装包并包含所有开发依赖项

测试详细程度控制

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

# Run all tests with debug output
make test LOG_LEVEL=DEBUG

# Run integration tests with info output
make integration-tests LOG_LEVEL=INFO

# Run unit tests with warning output (default)
make unit-tests LOG_LEVEL=WARNING

可用的日志级别：

  • DEBUG：显示所有调试消息，对详细的测试流程很有用

  • INFO：显示信息性消息及以上级别

  • WARNING：仅显示警告和错误（默认）

  • ERROR：仅显示错误消息

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - A tier

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ydb-platform/ydb-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server