YDB MCP
OfficialYDB MCP
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-mcpYDB 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を制限します。
ドメイン固有性 — 生のデータベースプリミティブではなく、ビジネスロジックに一致するツールをモデルに提供します。
シンプルさ — ツールが少ないほど、モデルにとっての曖昧さが減ります。
利用可能なメソッド
サブクラスでこれらをオーバーライドまたは呼び出します:
メソッド | 説明 |
| SQLクエリを実行します。 |
| クエリ実行計画を |
| YDBディレクトリを一覧表示します。 |
| YDBパス(テーブルスキーマ、ディレクトリなど)を記述します。 |
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: エラーメッセージのみを表示
Available Tools
7 toolsydb_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
Scored across 7 tools
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.
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.
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.
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
Related MCP Connectors
A Model Context Protocol server for Wix AI tools
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
MCP server for AI dialogue using various LLM models via AceDataCloud
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables Large Language Models to seamlessly interact with ClickHouse databases, supporting resource listing, schema retrieval, and query execution.2MIT
- AlicenseAqualityBmaintenanceA 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.1529MIT
- AlicenseAqualityCmaintenanceA Model Context Protocol server that enables large language models to access database metadata and perform cross-engine data querying across diverse database ecosystems.1654Apache 2.0
- AlicenseNot gradedqualityCmaintenanceMCP server for PostgreSQL, MySQL, and SQLite that gives AI assistants secure database access via the Model Context Protocol.47 npm5MIT