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을 고정된 읽기 전용 쿼리 세트로 제한합니다.

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

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

사용 가능한 메서드

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

params 인수는 일반 dict입니다. $ 접두사가 없는 키에는 자동으로 추가됩니다. 명시적인 YDB 유형을 지정하려면 (value, "TypeName") 튜플을 사용하십시오(예: {"id": (42, "Int64")}).

일반 도구 제어

generic_tools 클래스 속성을 사용하여 등록된 내장 도구를 제어하십시오:

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: 오류 메시지만 표시

Maintenance

Resources

• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• ydb_describe_pathC
• ydb_explain_queryC
• ydb_explain_query_with_paramsC
• ydb_list_directoryC
• ydb_queryC
• ydb_query_with_paramsC
• ydb_statusA