Local Ydb Toolkit

What astandrik/local-ydb-toolkit MCP server does

astandrik/local-ydb-toolkit MCP server exposes operational controls for Docker-based local-ydb deployments. It can work with a local Docker host or with a host reached through an SSH-backed profile. The toolset covers both plain root databases and tenant topologies with static and dynamic nodes.

Read-only operations provide Docker inventory, container logs, database and tenant checks, node registration, GraphShard visibility, monitoring health, authentication audits, storage placement, leftover-volume discovery, version listing, and schema inspection. Database features include structured YQL generation, DDL validation or application through the YDB JavaScript SDK, managed YQL query and explanation, and permission inspection.

The server also handles lifecycle and maintenance workflows. Available operations include prerequisite checks, bootstrap, image pulls, upgrades, root-password rotation, auth hardening, storage-group changes, dump-and-restore workflows, explicit cleanup, and complete stack destruction. The supplied tools distinguish between static and dynamic container roles where the operation requires it.

How it works

The server communicates over stdio and uses a selected profile to determine the Docker target, YDB paths, ports, credentials, storage settings, and related deployment details. Profile-based calls can receive an absolute configPath. Alternatively, the MCP client environment can define LOCAL_YDB_TOOLKIT_CONFIG as an absolute JSON configuration path. An explicitly supplied path must point to a readable regular JSON file no larger than 1 MiB; invalid or missing explicit files fail closed rather than silently selecting another profile.

Mutating tools follow a plan-first model. Without confirm=true, operations such as bootstrap, permission changes, schema application, image pulls, auth changes, storage resizing, cleanup, and destruction describe the intended action without making the change. Confirmed actions perform the operation and, where implemented, verify the resulting state. SQL execution also explains the statement first and only performs a NoTx execution after confirmation.

Setup and configuration

The repository publishes the local MCP package as @astandrik/local-ydb-mcp. Its documented launcher requires Node.js 20.19 or newer and npx; the pinned package version shown in the repository is 0.18.2. The repository also contains plugin integration for Claude Code, a Gemini CLI extension, and a Codex marketplace package, but the server itself is a local stdio process.

Use an absolute configuration path for profile-based operations. A configured rootPasswordFile can be checked during prerequisite and authentication workflows. SSH-backed profiles require a reachable target; an unreachable target is reported as unavailable rather than treated as proof that required host tools are missing.

Tools and capabilities

• Inspect Docker containers, volumes, daemon state, YDB status, health, logs, tenants, nodes, GraphShard state, and auth posture.
• Bootstrap root or tenant-based local-ydb topologies, including configured dynamic nodes.
• Generate, validate, explain, and apply supported YDB table DDL and managed YQL.
• Inspect or change permissions with confirmation-controlled plans.
• Prepare and apply native-auth hardening, write dynamic-node auth configuration, and rotate the root password.
• Inspect storage placement, resize storage groups, find leftovers, and perform explicit cleanup or dump/restore workflows.
• List image versions, start background pulls, check pull jobs, upgrade deployments, or destroy a stack.

Limitations and notes

The server is tailored to configured local-ydb deployments and does not present a general-purpose YDB endpoint interface. Its SQL tool runs managed YQL only against the selected profile. Cleanup removes only explicitly supplied host paths or Docker volumes, and discovery tools do not delete data. Some destructive or topology-changing workflows require additional preflight checks and confirmation. The repository describes the MCP package as unofficial and separates it from the official general-purpose YDB MCP server.