Local YDB MCP

@astandrik/local-ydb-mcp

Unofficial stdio MCP server for operating Docker-based local-ydb deployments.

Website: local-ydb-toolkit.ydb-qdrant.tech.

Relationship to ydb/ydb-mcp

This package is complementary to the official ydb-platform/ydb-mcp server. Use ydb/ydb-mcp for general YDB database-level tools such as ad hoc SQL queries, query explanations, directory listing, and path inspection against an existing YDB endpoint.

Use @astandrik/local-ydb-mcp when an agent needs to operate Docker-based local-ydb environments themselves: host prerequisite checks, root or tenant bootstrap, database healthcheck diagnostics, dynamic-node lifecycle, GraphShard checks, table DDL generation/validation/application for local deployments, auth hardening, storage workflows, dump/restore, and version upgrades. Its local_ydb_sql tool is deliberately narrower than ydb/ydb-mcp: it runs managed YQL only against the selected configured local-ydb profile. Mutating tools are plan-first and require confirm: true before they execute changes.

MCP Client Config

This package requires Node.js 20.19 or newer.

Inspect the installed CLI without starting the MCP server:

local-ydb-mcp --version

local-ydb-mcp --help

Or run the same commands through npm:

npx --yes @astandrik/local-ydb-mcp@latest --version

npx --yes @astandrik/local-ydb-mcp@latest --help

Each flag prints to stdout and exits with code 0, without loading the toolkit config. Unknown arguments, repeated flags, and combinations of flags print a usage error to stderr and exit with code 2. Only the long --version and --help flags are supported. Start without arguments for normal MCP stdio operation; do not add these diagnostic flags to the MCP client launch configuration.

Use npx so clients can run the server without a manual checkout:

{

"mcpServers": { "local-ydb": { "command": "npx", "args": ["-y", "--prefer-online", "@astandrik/local-ydb-mcp@latest"], "env": { "LOCAL_YDB_TOOLKIT_CONFIG": "/path/to/local-ydb.config.json" } } } }

This form checks the npm registry when the MCP server starts, so clients pick up newly published versions after restarting the MCP client.

The config file is optional. If LOCAL_YDB_TOOLKIT_CONFIG is not set, the server reads local-ydb.config.json from the current working directory. A present but empty environment value is explicit and returns CONFIG_PATH_NOT_ABSOLUTE. If the implicit file is absent, the server uses a default local profile with ghcr.io/ydb-platform/local-ydb:stable-26-1-1. LOCAL_YDB_TOOLKIT_CONFIG and per-call configPath values must be absolute and must name a readable regular JSON file no larger than 1 MiB. The configured defaultProfile must name an existing profiles entry. Missing, unreadable, oversized, malformed, or schema-invalid explicit files fail closed and return a stable error code without exposing file contents, parser snippets, or the absolute path.

The named upstream default tag is mutable. Set profiles. .image explicitly to control upgrades; use a digest for immutable pulls, noting that local_ydb_upgrade_version does not accept digest-pinned source profiles.

After a package update changes the implicit default, an existing stack created with the previous default will fail the profile compatibility check instead of mixing YDB images. Add the stack's current image reference to a file-backed profile before restart or bootstrap, then use local_ydb_upgrade_version for an intentional dump-and-rebuild upgrade.

Official MCP Registry metadata uses the name io.github.astandrik/local-ydb-mcp and is published from the repository root server.json after the matching npm version is available.

MCP Features

The server exposes local-ydb operation tools and static MCP prompts. Prompt templates guide stack diagnosis, root database bootstrap, tenant topology bootstrap, database diagnostics, schema generation/apply, version upgrades, auth hardening, and storage group reduction. Prompts return workflow instructions only; they do not execute commands. A prompt configPath, when supplied, must be an absolute path just like the corresponding tool argument.

Mutating tools remain plan-only unless called with confirm: true.

Tools

The server exposes 39 tools. This index is generated from the runtime tool registry; edit toolDefinitions and run npm run docs:generate to update it.

Checks

Schema

Sql

Auth

| local_ydb_set_root_password | plan-first mutation | Rotate the runtime root password with ALTER USER and sync the host auth config and root password file to match. YDB may reject passwords that violate auth_config.password_comple