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:

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:

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

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