mcpField
Y
YDB MCP

YDB MCP

ローカル
github.com/ydb-platformデータベース295 週間前に更新
リポジトリ

YDB MCP について

YDB MCP は YDB データベース向けの MCP サーバーで、MCP に対応した任意の LLM から YDB インスタンスを操作できます。クエリはデフォルトで読み取り専用として実行され、書き込みは明示的に有効化する必要があります。固定のクエリのみを公開するカスタムサーバーの基盤としても利用できます。

主な機能

  1. 01SQL とパラメータ付きクエリの実行
  2. 02実行計画とディレクトリの参照
  3. 03デフォルトは読み取り専用で書き込みは任意に有効化
  4. 04複数の認証方式に対応
  5. 05カスタムツール用のサブクラス化可能なサーバー

活用シーン

  1. 01LLM による YDB データの自然言語クエリ
  2. 02業務アプリケーション向けの固定された読み取り専用ツールの提供

MCP 対応

本プロジェクトは MCP サーバーであり、クエリ実行、実行計画の取得、ディレクトリ一覧、パス情報の参照用ツールを MCP クライアントに公開します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "ydb-mcp"
      ]
    }
  }
}
起動コマンドuvx ydb-mcp

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
pypiydb-mcp

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

YDB MCP

License PyPI version

YDB 用の Model Context Protocol サーバーです。MCP に対応するあらゆる LLM から YDB データベースを操作できます。この統合により、YDB インスタンスでの AI を活用したデータベース操作や、自然言語によるやり取りが可能になります。

YDB MCP サーバー

使用方法

uvx を使用する

uvx は uv run tool の別名で、Python アプリケーションを明示的にインストールせずに実行できます。以下に、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 クライアントの設定に追加してください。また、Python インタープリターのパスを、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"
      ]
    }
  }
}
サービスアカウント認証を使用する

サービスアカウント認証には yandexcloud パッケージが必要ですが、これはデフォルトではインストールされていません。YDB MCP を実行する環境で利用できることを確認してください。

  • uvx：--with yandexcloud を ydb-mcp の前に指定して、その場で追加します。
  • pipx：pipx install ydb-mcp の後に pipx inject ydb-mcp yandexcloud を実行し、追加パッケージとともに YDB MCP をインストールします。
  • pip：pip install ydb-mcp yandexcloud を実行し、YDB MCP とともにインストールします。

サービスアカウント認証を使用するには、--ydb-auth-mode と --ydb-sa-key-file の引数を指定します。

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "--with", "yandexcloud",
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local",
        "--ydb-auth-mode", "service-account",
        "--ydb-sa-key-file", "~/sa_key.json"
      ]
    }
  }
}
TLS 接続

TLS 経由で接続するには、grpcs:// エンドポイントを使用します。クラスター証明書がプライベート CA によって発行されている場合は、ルート証明書を含む PEM ファイルのパスを --ydb-root-certificates で指定してください。それ以外の場合は、システムの信頼ストアが使用されます。

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpcs://localhost:2135",
        "--ydb-database", "/local",
        "--ydb-root-certificates", "~/ydb_ca.pem"
      ]
    }
  }
}
クエリの実行

サーバーはデフォルトでクエリを読み取り専用モードで実行します。読み取り専用クエリでは、YDB のネイティブなスナップショット読み取り専用トランザクションを使用するため、SQL テキストの照合に頼らず、データとスキーマへの書き込みが YDB 自体によって拒否されます。このモードは、組み込みのクエリツールと YDBMCPServer.execute() を呼び出すカスタムツールの両方に適用されます。

書き込みクエリを明示的に許可するには、--ydb-allow-write を設定します。

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

同じ設定は YDB_ALLOW_WRITE=true でも指定できます。書き込みが必要な場合にのみ有効にし、サーバーがデータを変更する必要がない場合は、追加の権限境界として読み取り専用の YDB 認証情報を使用することをおすすめします。

利用可能なツール

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：エラーメッセージのみを表示します

コメント

Markdown 対応

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。