Skip to main content
Glama
YDB MCP

YDB MCP

Official
by ydb-platform

YDB MCP


License PyPI version

YDB를 위한 Model Context Protocol 서버입니다. MCP를 지원하는 모든 LLM에서 YDB 데이터베이스를 작업할 수 있게 해줍니다. 이 통합을 통해 YDB 인스턴스에 대한 AI 기반 데이터베이스 작업 및 자연어 상호작용이 가능해집니다.

사용법

uvx 사용

uv run tool의 별칭인 uvx를 사용하면 명시적으로 설치하지 않고도 다양한 파이썬 애플리케이션을 실행할 수 있습니다. 아래는 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를 시작하려면 YDB 인스턴스와 통신하도록 MCP 클라이언트를 구성해야 합니다. 아래는 설정에 따라 사용자 정의하고 MCP 클라이언트 설정에 넣을 수 있는 구성 파일 예시입니다. 파이썬 인터프리터 경로는 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: GreptimeDB MCP 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 연결 위에 자신만의 도구를 추가할 수 있으며, 선택적으로 내장된 일반 도구를 비활성화하여 애플리케이션에 필요한 쿼리만 노출할 수 있습니다.

왜 사용자 정의 서버를 구축하나요?

  • 보안 — 임의의 SQL 실행을 노출하는 대신 LLM을 고정된 읽기 전용 쿼리 세트로 제한합니다.

  • 도메인 특수성 — 원시 데이터베이스 기본 요소가 아닌 비즈니스 로직에 맞는 도구를 모델에 제공합니다.

  • 단순성 — 도구가 적을수록 모델의 모호성이 줄어듭니다.

사용 가능한 메서드

서브클래스에서 다음을 재정의하거나 호출하십시오:

메서드

설명

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: 모든 린트 검사 실행(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: 오류 메시지만 표시

Available Tools

7 tools
ydb_describe_pathC

Get detailed information about a YDB path

Inputs: path (required). Returns: result

ydb_explain_queryC

Explain a SQL query against YDB

Inputs: sql (required). Returns: result

ydb_explain_query_with_paramsC

Explain a parameterized SQL query against YDB

Inputs: sql (required), params (required). Returns: result

ydb_list_directoryC

List directory contents in YDB

Inputs: path (required). Returns: result

ydb_queryB

Run a read-only SQL query against YDB database

Inputs: sql (required). Returns: result

ydb_query_with_paramsC

Run a read-only parameterized SQL query with JSON parameters

Inputs: sql (required), params (required). Returns: result

ydb_statusA

Get the current YDB connection status

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a clearly distinct purpose: executing vs explaining queries, with vs without parameters, and separate tools for status, directory listing, and path details. No two tools are ambiguous or likely to be confused during selection.

    Naming Consistency4/5

    All tools share the ydb_ prefix, and most follow a verb_noun pattern (list_directory, describe_path) with a consistent with_params modifier. Minor deviations like the noun-only ydb_status and ydb_query are still predictable and do not hinder readability.

    Tool Count5/5

    Seven tools is well-scoped for a database server focused on read-only operations, covering queries, explanations, status, and structural navigation without overflow or sparse coverage.

    Completeness5/5

    The server's read-only scope is fully covered: plain and parameterized queries, explain plans for both, connection status, and directory/path inspection. No obvious missing operations are needed for the intended use case.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables Large Language Models to seamlessly interact with ClickHouse databases, supporting resource listing, schema retrieval, and query execution.
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A Model Context Protocol server implementation that enables AI assistants to securely interact with GreptimeDB, allowing them to explore database schema, read data, and execute SQL queries through a controlled interface.
      15
      29
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for PostgreSQL, MySQL, and SQLite that gives AI assistants secure database access via the Model Context Protocol.
      49 npm
      5
      MIT