ydb/ydb-mcp

---
Model Context Protocol server for YDB. It allows to work with YDB databases from any LLM that supports MCP. This integration enables AI-powered database operations and natural language interactions with your YDB instances.
Usage
Via uvx
uvx, which is an allias for uv run tool, allows you to run various python applications without explicitly installing them. Below are examples of how to configure YDB MCP using uvx.
Example: Using Anonymous Authentication
Via pipx
pipx allows you to run various applications from PyPI without explicitly installing each one. However, it must be installed first. Below are examples of how to configure YDB MCP using pipx.
Example: Using Anonymous Authentication
Via pip
YDB MCP can be installed using pip, Python's package installer. The package is available on PyPI and includes all necessary dependencies.
To get started with YDB MCP, you'll need to configure your MCP client to communicate with the YDB instance. Below are example configuration files that you can customize according to your setup and then put into MCP client's settings. Path to the Python interpreter might also need to be adjusted to the correct virtual environment that has the ydb-mcp package installed.
Example: Using Anonymous Authentication
Authentication
Regardless of the usage method (uvx, pipx or pip), you can configure authentication for your YDB installation. To do this, pass special command line arguments.
Using Login/Password Authentication
To use login/password authentication, specify the --ydb-auth-mode, --ydb-login, and --ydb-password arguments:
Using Access Token Authentication
To use access token authentication, specify the --ydb-auth-mode and --ydb-access-token arguments:
Using Service Account Authentication
Service account authentication requires the yandexcloud package, which is **not** installed by default. Make sure it is available in the environment that runs YDB MCP:
- **uvx**: add it on the fly with --with yandexcloud (passed before ydb-mcp).
- **pipx**: install YDB MCP with the extra package using pipx install ydb-mcp followed by pipx inject ydb-mcp yandexcloud.
- **pip**: install it alongside YDB MCP with pip install ydb-mcp yandexcloud.
To use service account authentication, specify the --ydb-auth-mode and --ydb-sa-key-file arguments:
TLS Connections
Use a grpcs:// endpoint to connect over TLS. If the cluster certificate is issued by a private CA, pass a path to the PEM file with its root certificates via --ydb-root-certificates; otherwise the system trust store is used:
Write Queries
The server runs queries in read-only mode by default. Read-only queries use native YDB snapshot read-only transactions,
so data and schema writes are rejected by YDB itself without relying on SQL text matching. The mode applies to both
built-in query tools and custom tools that call YDBMCPServer.execute().
To explicitly allow write queries, set --ydb-allow-write:
The same setting can be provided through YDB_ALLOW_WRITE=true. Enable it only when writes are intended, and
prefer read-only YDB credentials as an additional permission boundary whenever the server does not need to modify data.
Available Tools
YDB MCP provides the following tools for interacting with YDB databases:
- ydb_query: Run a SQL query against a YDB database
- Parameters:
- sql: SQL query string to execute
- ydb_query_with_params: Run a parameterized SQL query with JSON parameters
- Parameters:
- sql: SQL query string with parameter placeholders
- params: JSON string containing parameter values