Skip to main content
Glama
YDB MCP

YDB MCP

Official
by ydb-platform

YDB MCP


License PyPI version

Model Context Protocol-Server für YDB. Er ermöglicht die Arbeit mit YDB-Datenbanken von jedem LLM aus, das MCP unterstützt. Diese Integration ermöglicht KI-gestützte Datenbankoperationen und Interaktionen in natürlicher Sprache mit Ihren YDB-Instanzen.

Verwendung

Via uvx

uvx, ein Alias für uv run tool, ermöglicht es Ihnen, verschiedene Python-Anwendungen auszuführen, ohne sie explizit installieren zu müssen. Nachfolgend finden Sie Beispiele für die Konfiguration von YDB MCP mit uvx.

Beispiel: Verwendung von anonymer Authentifizierung

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

Via pipx

pipx ermöglicht es Ihnen, verschiedene Anwendungen von PyPI auszuführen, ohne jede einzelne explizit installieren zu müssen. Es muss jedoch zuerst installiert werden. Nachfolgend finden Sie Beispiele für die Konfiguration von YDB MCP mit pipx.

Beispiel: Verwendung von anonymer Authentifizierung

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

Via pip

YDB MCP kann mit pip, dem Python-Paket-Installer, installiert werden. Das Paket ist auf PyPI verfügbar und enthält alle notwendigen Abhängigkeiten.

pip install ydb-mcp

Um mit YDB MCP zu beginnen, müssen Sie Ihren MCP-Client so konfigurieren, dass er mit der YDB-Instanz kommuniziert. Nachfolgend finden Sie Beispiel-Konfigurationsdateien, die Sie an Ihr Setup anpassen und dann in die Einstellungen des MCP-Clients übernehmen können. Der Pfad zum Python-Interpreter muss möglicherweise ebenfalls an die korrekte virtuelle Umgebung angepasst werden, in der das Paket ydb-mcp installiert ist.

Beispiel: Verwendung von anonymer Authentifizierung

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

Authentifizierung

Unabhängig von der Verwendungsmethode (uvx, pipx oder pip) können Sie die Authentifizierung für Ihre YDB-Installation konfigurieren. Übergeben Sie dazu spezielle Befehlszeilenargumente.

Verwendung der Login/Passwort-Authentifizierung

Um die Login/Passwort-Authentifizierung zu verwenden, geben Sie die Argumente --ydb-auth-mode, --ydb-login und --ydb-password an:

{
  "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>"
      ]
    }
  }
}

Verwendung der Zugriffstoken-Authentifizierung

Um die Zugriffstoken-Authentifizierung zu verwenden, geben Sie die Argumente --ydb-auth-mode und --ydb-access-token an:

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

Verwendung der Service-Account-Authentifizierung

Um die Service-Account-Authentifizierung zu verwenden, geben Sie die Argumente --ydb-auth-mode und --ydb-sa-key-file an:

{
  "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

Verfügbare Tools

YDB MCP stellt die folgenden Tools für die Interaktion mit YDB-Datenbanken bereit:

  • ydb_query: Führt eine SQL-Abfrage gegen eine YDB-Datenbank aus

    • Parameter:

      • sql: Auszuführende SQL-Abfragezeichenfolge

  • ydb_query_with_params: Führt eine parametrisierte SQL-Abfrage mit JSON-Parametern aus

    • Parameter:

      • sql: SQL-Abfragezeichenfolge mit Platzhaltern für Parameter

      • params: JSON-Zeichenfolge, die Parameterwerte enthält

  • ydb_explain_query: Erklärt eine SQL-Abfrage (gibt den Ausführungsplan zurück)

    • Parameter:

      • sql: Zu erklärende SQL-Abfragezeichenfolge

  • ydb_explain_query_with_params: Erklärt eine parametrisierte SQL-Abfrage

    • Parameter:

      • sql: SQL-Abfragezeichenfolge mit Platzhaltern für Parameter

      • params: JSON-Zeichenfolge, die Parameterwerte enthält

  • ydb_list_directory: Listet Verzeichnisinhalte in YDB auf

    • Parameter:

      • path: Aufzulistender YDB-Verzeichnispfad

  • ydb_describe_path: Ruft detaillierte Informationen zu einem YDB-Pfad ab (Tabelle, Verzeichnis usw.)

    • Parameter:

      • path: Zu beschreibender YDB-Pfad

  • ydb_status: Ruft den aktuellen Status der YDB-Verbindung ab

Erstellen benutzerdefinierter MCP-Server

YDBMCPServer ist darauf ausgelegt, unterklassifiziert zu werden. Sie können Ihre eigenen Tools auf einer bestehenden YDB-Verbindung hinzufügen und optional die integrierten generischen Tools deaktivieren, um nur die Abfragen offenzulegen, die Ihre Anwendung benötigt.

Warum einen benutzerdefinierten Server erstellen?

  • Sicherheit — Beschränken Sie das LLM auf einen festen Satz schreibgeschützter Abfragen, anstatt beliebige SQL-Ausführungen zu ermöglichen.

  • Domänenspezifität — Geben Sie dem Modell Tools, die Ihrer Geschäftslogik entsprechen, anstatt roher Datenbank-Primitive.

  • Einfachheit — Weniger Tools bedeuten weniger Mehrdeutigkeit für das Modell.

Verfügbare Methoden

Überschreiben oder rufen Sie diese in Ihrer Unterklasse auf:

Methode

Beschreibung

await self.execute(sql, params=None)

Führt eine SQL-Abfrage aus. Gibt list[dict] zurück, jedes Dict hat "columns" und "rows".

await self.explain(sql, params=None)

Gibt den Abfrageausführungsplan als dict zurück.

await self.list_directory(path)

Listet ein YDB-Verzeichnis auf. Gibt dict mit "path" und "items" zurück.

await self.describe_path(path)

Beschreibt einen YDB-Pfad (Tabellenschema, Verzeichnis usw.). Gibt ein dict zurück.

Das Argument params ist ein einfaches dict. Schlüssel ohne ein $-Präfix erhalten dieses automatisch hinzugefügt. Um einen expliziten YDB-Typ anzugeben, verwenden Sie ein (value, "TypeName")-Tupel — z. B. {"id": (42, "Int64")}.

Steuerung generischer Tools

Verwenden Sie das Klassenattribut generic_tools, um zu steuern, welche integrierten Tools registriert werden:

Wert

Effekt

set(YDBGenericTool)

Alle integrierten Tools (Standard)

set()

Keine integrierten Tools — nur Ihre eigenen

{YDBGenericTool.QUERY, YDBGenericTool.STATUS}

Nur die aufgelisteten Tools

YDBGenericTool ist ein String-Enum — verfügbare Werte: QUERY, QUERY_WITH_PARAMS, EXPLAIN, EXPLAIN_WITH_PARAMS, STATUS, LIST_DIRECTORY, DESCRIBE_PATH.

Beispiel

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

Führen Sie es direkt aus:

python my_server.py

Oder binden Sie es als MCP-Server in Ihrer Client-Konfiguration ein:

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

Entwicklung

Das Projekt verwendet Make als primäres Entwicklungstool und bietet eine konsistente Schnittstelle für allgemeine Entwicklungsaufgaben.

Verfügbare Make-Befehle

Das Projekt enthält ein umfassendes Makefile mit verschiedenen Befehlen für Entwicklungsaufgaben. Jeder Befehl wurde entwickelt, um den Entwicklungsworkflow zu optimieren und die Codequalität sicherzustellen:

  • make all: Führt nacheinander clean, lint und test aus (Standardziel)

  • make clean: Entfernt alle Build-Artefakte und temporären Dateien

  • make test: Führt alle Tests mit pytest aus

    • Kann mit Umgebungsvariablen konfiguriert werden:

      • LOG_LEVEL (Standard: WARNING) - Steuert die Ausführlichkeit der Testausgabe (DEBUG, INFO, WARNING, ERROR)

  • make unit-tests: Führt nur Unit-Tests mit ausführlicher Ausgabe aus

    • Kann mit Umgebungsvariablen konfiguriert werden:

      • LOG_LEVEL (Standard: WARNING) - Steuert die Ausführlichkeit der Testausgabe (DEBUG, INFO, WARNING, ERROR)

  • make integration-tests: Führt nur Integrationstests mit ausführlicher Ausgabe aus

    • Kann mit Umgebungsvariablen konfiguriert werden:

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

      • YDB_DATABASE (Standard: /local)

      • MCP_HOST (Standard: 127.0.0.1)

      • MCP_PORT (Standard: 8989)

      • LOG_LEVEL (Standard: WARNING) - Steuert die Ausführlichkeit der Testausgabe (DEBUG, INFO, WARNING, ERROR)

  • make run-server: Startet den YDB MCP-Server

    • Kann mit Umgebungsvariablen konfiguriert werden:

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

      • YDB_DATABASE (Standard: /local)

    • Zusätzliche Argumente können mit ARGS="your args" übergeben werden

  • make lint: Führt alle Linting-Prüfungen aus (flake8, mypy, black, isort)

  • make format: Formatiert Code mit black und isort

  • make install: Installiert das Paket im Entwicklungsmodus

  • make dev: Installiert das Paket im Entwicklungsmodus mit allen Entwicklungsabhängigkeiten

Steuerung der Test-Ausführlichkeit

Standardmäßig werden Tests mit minimaler Ausgabe (WARNING-Ebene) ausgeführt, um die Ausgabe sauber zu halten. Sie können die Ausführlichkeit der Testausgabe mit der Umgebungsvariablen LOG_LEVEL steuern:

# 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

Verfügbare Log-Ebenen:

  • DEBUG: Zeigt alle Debug-Meldungen an, nützlich für detaillierte Testabläufe

  • INFO: Zeigt Informationsmeldungen und höher an

  • WARNING: Zeigt nur Warnungen und Fehler an (Standard)

  • ERROR: Zeigt nur Fehlermeldungen an

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

    ActivitySlowing
    ResponsivenessLimited 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