YDB MCP

Servidor del Protocolo de Contexto de Modelo para YDB. Permite trabajar con bases de datos YDB desde cualquier LLM que admita MCP. Esta integración permite realizar operaciones de base de datos impulsadas por IA e interacciones en lenguaje natural con sus instancias de YDB.

Uso

A través de uvx

uvx, que es un alias para uv run tool, le permite ejecutar varias aplicaciones de Python sin instalarlas explícitamente. A continuación, se muestran ejemplos de cómo configurar YDB MCP usando uvx.

Ejemplo: Uso de autenticación anónima

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

A través de pipx

pipx le permite ejecutar varias aplicaciones desde PyPI sin instalar explícitamente cada una. Sin embargo, primero debe estar instalado. A continuación, se muestran ejemplos de cómo configurar YDB MCP usando pipx.

Ejemplo: Uso de autenticación anónima

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

A través de pip

YDB MCP se puede instalar usando pip, el instalador de paquetes de Python. El paquete está disponible en PyPI e incluye todas las dependencias necesarias.

pip install ydb-mcp

Para comenzar con YDB MCP, deberá configurar su cliente MCP para comunicarse con la instancia de YDB. A continuación, se muestran ejemplos de archivos de configuración que puede personalizar según su configuración y luego colocar en la configuración del cliente MCP. Es posible que también deba ajustar la ruta al intérprete de Python al entorno virtual correcto que tenga instalado el paquete ydb-mcp.

Ejemplo: Uso de autenticación anónima

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

Autenticación

Independientemente del método de uso (uvx, pipx o pip), puede configurar la autenticación para su instalación de YDB. Para hacer esto, pase argumentos especiales de línea de comandos.

Uso de autenticación de usuario/contraseña

Para usar la autenticación de usuario/contraseña, especifique los argumentos --ydb-auth-mode, --ydb-login y --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>"
      ]
    }
  }
}

Uso de autenticación mediante token de acceso

Para usar la autenticación mediante token de acceso, especifique los argumentos --ydb-auth-mode y --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"
      ]
    }
  }
}

Uso de autenticación de cuenta de servicio

Para usar la autenticación de cuenta de servicio, especifique los argumentos --ydb-auth-mode y --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

Herramientas disponibles

YDB MCP proporciona las siguientes herramientas para interactuar con bases de datos YDB:

• ydb_query: Ejecutar una consulta SQL en una base de datos YDB

  • Parámetros:

    • sql: Cadena de consulta SQL a ejecutar

• ydb_query_with_params: Ejecutar una consulta SQL parametrizada con parámetros JSON

  • Parámetros:

    • sql: Cadena de consulta SQL con marcadores de posición de parámetros

    • params: Cadena JSON que contiene los valores de los parámetros

• ydb_explain_query: Explicar una consulta SQL (devuelve el plan de ejecución)

  • Parámetros:

    • sql: Cadena de consulta SQL a explicar

• ydb_explain_query_with_params: Explicar una consulta SQL parametrizada

  • Parámetros:

    • sql: Cadena de consulta SQL con marcadores de posición de parámetros

    • params: Cadena JSON que contiene los valores de los parámetros

• ydb_list_directory: Listar el contenido del directorio en YDB

  • Parámetros:

    • path: Ruta del directorio YDB a listar

• ydb_describe_path: Obtener información detallada sobre una ruta YDB (tabla, directorio, etc.)

  • Parámetros:

    • path: Ruta YDB a describir

• ydb_status: Obtener el estado actual de la conexión YDB

Creación de servidores MCP personalizados

YDBMCPServer está diseñado para ser heredado. Puede agregar sus propias herramientas sobre una conexión YDB establecida y, opcionalmente, deshabilitar las herramientas genéricas integradas para exponer solo las consultas que su aplicación necesita.

¿Por qué crear un servidor personalizado?

• Seguridad: restrinja el LLM a un conjunto fijo de consultas de solo lectura en lugar de exponer la ejecución arbitraria de SQL.

• Especificidad del dominio: proporcione al modelo herramientas que coincidan con su lógica de negocio en lugar de primitivas de base de datos sin procesar.

• Simplicidad: menos herramientas significan menos ambigüedad para el modelo.

Métodos disponibles

Invalide o llame a estos en su subclase:

El argumento params es un dict simple. Las claves sin un prefijo $ lo reciben automáticamente. Para especificar un tipo YDB explícito, use una tupla (value, "TypeName") — p. ej. {"id": (42, "Int64")}.

Control de herramientas genéricas

Use el atributo de clase generic_tools para controlar qué herramientas integradas se registran:

YDBGenericTool es una enumeración de cadenas: valores disponibles: QUERY, QUERY_WITH_PARAMS, EXPLAIN, EXPLAIN_WITH_PARAMS, STATUS, LIST_DIRECTORY, DESCRIBE_PATH.

Ejemplo

# 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()

Ejecútelo directamente:

python my_server.py

O configúrelo como un servidor MCP en la configuración de su cliente:

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

Desarrollo

El proyecto utiliza Make como su herramienta de desarrollo principal, proporcionando una interfaz consistente para tareas de desarrollo comunes.

Comandos de Make disponibles

El proyecto incluye un Makefile completo con varios comandos para tareas de desarrollo. Cada comando está diseñado para agilizar el flujo de trabajo de desarrollo y garantizar la calidad del código:

• make all: Ejecutar clean, lint y test en secuencia (objetivo predeterminado)

• make clean: Eliminar todos los artefactos de compilación y archivos temporales

• make test: Ejecutar todas las pruebas usando pytest

  • Se puede configurar con variables de entorno:

    • LOG_LEVEL (predeterminado: WARNING) - Controlar la verbosidad de la salida de prueba (DEBUG, INFO, WARNING, ERROR)

• make unit-tests: Ejecutar solo pruebas unitarias con salida detallada

  • Se puede configurar con variables de entorno:

    • LOG_LEVEL (predeterminado: WARNING) - Controlar la verbosidad de la salida de prueba (DEBUG, INFO, WARNING, ERROR)

• make integration-tests: Ejecutar solo pruebas de integración con salida detallada

  • Se puede configurar con variables de entorno:

    • YDB_ENDPOINT (predeterminado: grpc://localhost:2136)

    • YDB_DATABASE (predeterminado: /local)

    • MCP_HOST (predeterminado: 127.0.0.1)

    • MCP_PORT (predeterminado: 8989)

    • LOG_LEVEL (predeterminado: WARNING) - Controlar la verbosidad de la salida de prueba (DEBUG, INFO, WARNING, ERROR)

• make run-server: Iniciar el servidor YDB MCP

  • Se puede configurar con variables de entorno:

    • YDB_ENDPOINT (predeterminado: grpc://localhost:2136)

    • YDB_DATABASE (predeterminado: /local)

  • Se pueden pasar argumentos adicionales usando ARGS="your args"

• make lint: Ejecutar todas las comprobaciones de linting (flake8, mypy, black, isort)

• make format: Formatear código usando black e isort

• make install: Instalar el paquete en modo de desarrollo

• make dev: Instalar el paquete en modo de desarrollo con todas las dependencias de desarrollo

Control de verbosidad de pruebas

De forma predeterminada, las pruebas se ejecutan con una salida mínima (nivel WARNING) para mantener la salida limpia. Puede controlar la verbosidad de la salida de prueba utilizando la variable de entorno 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

Niveles de registro disponibles:

• DEBUG: Mostrar todos los mensajes de depuración, útil para un flujo de prueba detallado

• INFO: Mostrar mensajes informativos y superiores

• WARNING: Mostrar solo advertencias y errores (predeterminado)

• ERROR: Mostrar solo mensajes de error