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.

<a href="https://glama.ai/mcp/servers/@ydb-platform/ydb-mcp">

</a>

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

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

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

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

Via pip

YDB MCP can be installed using pip, Python's package installer. The package is available on PyPI and includes all necessary dependencies.

pip install ydb-mcp

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

{
  "mcpServers": {
    "ydb": {
      "command": "python3",
      "args": [
        "-m", "ydb_mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local"
      ]
    }
  }
}

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:

{
  "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>"
      ]
    }
  }
}

Using Access Token Authentication

To use access token authentication, specify the --ydb-auth-mode and --ydb-access-token arguments:

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local",
        "--ydb-auth-mode", "access-token",
        "--ydb-access-token", "qwerty123"
      ]
    }
  }
}

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:

{
  "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"
      ]
    }
  }
}

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

- ydb_explain_query: Explain a SQL query (returns the execution plan)
- Parameters:
- sql: SQL query string to explain

- ydb_explain_query_with_params: Explain a parameterized SQL query
- Parameters:
- sql: SQL query string with parameter placeholders
- params: JSON string containing parameter values

- ydb_list_directory: List directory contents in YDB
- Parameters:
- path: YDB directory path to list

- ydb_describe_path: Get detailed information about a YDB path (table, directory, etc.)
- Parameters:
- path: YDB path to describe

- ydb_status: Get the current status of the YDB connection

Building Custom MCP Servers

YDBMCPServer is designed to be subclassed. You can add your own tools on top of an established YDB connection and, optionally, disable the built-in generic tools to expose only the queries your application needs.

Why build a custom server?

- Security — restrict the LLM to a fixed set of read-only queries instead of exposing arbitrary SQL execution.
- Domain specificity — give the model tools that match your business logic rather than raw database primitives.
- Simplicity — fewer tools means less ambiguity for the model.

Available methods

Override or call these in your subclass:

| Method | Description |
|--------|-------------|
| await self.execute(sql, params=None) | Run a SQL query. Returns list[dict], each dict has "columns" and "rows". |
| await self.explain(sql, params=None) | Return the query execution plan as a dict. |
| await self.list_directory(path) | List a YDB directory. Returns dict with "path" and "items". |
| await self.describe_path(path) | Describe a YDB path (table schema, directory, etc.). Returns a dict. |

The params argument is a plain dict. Keys without a $ prefix get it added automatically. To specify an explicit YDB type, use a (value, "TypeName") tuple — e.g. {"id": (42, "Int64")}.

Controlling generic tools

Use the generic_tools class attribute to control which built-in tools are registered:

| Value | Effect |
|---|---|
| set(YDBGenericTool) | All built-in tools (default) |
| set() | No built-in tools — only your own |
| {YDBGenericTool.QUERY, YDBGenericTool.STATUS} | Only the listed tools |

YDBGenericTool is a string enum — available values: QUERY, QUERY_WITH_PARAMS, EXPLAIN, EXPLAIN_WITH_PARAMS, STATUS, LIST_DIRECTORY, DESCRIBE_PATH.

Example

```python