YDB MCP

👁 License
👁 PyPI version

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

使用方法

uvx経由

uv run toolのエイリアスであるuvxを使用すると、明示的にインストールすることなく様々な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"
 ]
 }
 }
}

サービスアカウント認証の使用

サービスアカウント認証を使用するには、--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