# astandrik/local-ydb-toolkit [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/astandrik/local-ydb-toolkit  
**GitHub Stars:** 4  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/astandrik-local-ydb-toolkit

## Description
Local YDB MCP is a TypeScript stdio MCP server for operating Docker-based local-ydb deployments via local or SSH-backed profiles. Supports bootstrap, diagnostics, auth hardening, storage workflows, dump/restore, upgrades, and plan-first mutating operations.

## Tools
Capabilities this server exposes over MCP:

- **local_ydb_inventory** — Read-only Docker inventory for a local-ydb target profile. Success returns ok=true, Docker CLI/daemon state, containers, volumes, and inspect data for configured containers that actually exist; Docker CLI, daemon, or inventory failures return ok=false with a reason and omit inventory arrays so fail…
- **local_ydb_database_status** — Read-only YDB admin database status for the configured tenant path. Returns the command, stdout, stderr, and ok flag; use this for tenant state before bootstrap/restart troubleshooting, and use local_ydb_tenant_check for scheme reachability.
- **local_ydb_healthcheck** — Read-only YDB monitoring healthcheck for the configured tenant or root database. Uses the official YDB CLI SelfCheck path, returns selfCheckResult, issue counts, issue types, capped raw output, and whether the database is healthy; a requested noCache/noMerge option rejected with the exact recognize…
- **local_ydb_container_logs** — Read recent Docker logs from the configured static or primary dynamic local-ydb container. Use when bootstrap, restart, or readiness checks fail; target selects the container role and lines controls the tail length.
- **local_ydb_status_report** — Read-only aggregate report for quick diagnosis. Runs local_ydb_inventory, local_ydb_auth_check, local_ydb_tenant_check, local_ydb_nodes_check, and local_ydb_healthcheck, returning each result; every component is isolated so an unexpected failure produces a safe component-shaped fallback and does no…
- **local_ydb_tenant_check** — Read-only check that uses the YDB CLI to verify the configured tenant path is reachable. Use after bootstrap or restore to confirm tenant metadata before node or GraphShard checks.
- **local_ydb_scheme** — Read-only YDB scheme list or describe with capped stdout/stderr. It uses the root database for rootDatabase paths and the tenant database otherwise; list supports recursive/long/onePerLine flags, describe supports stats, and incompatible flag combinations are rejected.
- **local_ydb_nodes_check** — Read-only check of dynamic node registration through viewer/json nodelist. Use after starting, adding, or removing dynamic nodes; use local_ydb_tenant_check first when tenant reachability is unknown.
- **local_ydb_graphshard_check** — Read-only GraphShard check through viewer/json capabilities and tabletinfo for the configured tenant. Returns graphShardExists, tablet ids, and viewer status details; use after tenant bootstrap when GraphShard support or tablet visibility is the specific question.
- **local_ydb_auth_check** — Read-only auth audit that checks anonymous viewer whoami status and configured YDB CLI tenant access, using root credentials when rootPasswordFile is configured. Use after auth hardening or password rotation to verify the expected posture.
- **local_ydb_storage_placement** — Read-only storage inspection that returns ReadStoragePool output and BSC physical placement. Use before adding or reducing storage groups to confirm the exact pool shape.
- **local_ydb_storage_leftovers** — Read-only search for candidate leftover local-ydb Docker volumes, dumps, and PDisk/data paths. It scans Docker volume names plus profile.storageSearchPaths and deletes nothing; use before local_ydb_cleanup_storage to decide exact paths or volumes to remove.
- **local_ydb_list_versions** — List published GHCR or Docker Hub tags for a local-ydb container image, with numeric version tags sorted newest first. Use before local_ydb_upgrade_version; registry pagination and authentication are restricted to trusted origins, and pageSize and maxPages bound pagination.
- **local_ydb_pull_status** — Check the status of a background Docker image pull started by local_ydb_pull_image. For known jobs it returns a monotonic progressPercent based on completed known Docker layers rather than bytes: 0-99 while running, 100 after successful completion, and the last observed value after failure.
- **local_ydb_generate_schema** — Read-only structured YDB table DDL generator. It renders strict JSON specs for CREATE TABLE, ALTER TABLE, DROP TABLE, and secondary indexes, returns the generated script with official references and warnings, and can optionally validate through the YDB JS SDK without applying changes.
- **local_ydb_apply_schema** — Validate or apply YDB table DDL through the official YDB JS SDK. It accepts raw YQL DDL for PRAGMA plus CREATE TABLE, ALTER TABLE, and DROP TABLE; action=apply validates first and executes only with confirm=true.
- **local_ydb_sql** — Run managed YQL v1 against the configured local-ydb target through Query Service. query uses SnapshotRO, explain returns plan/AST, and execute always runs EXPLAIN first and sends one NoTx execution only with confirm=true.
- **local_ydb_permissions** — Inspect or change YDB scheme permissions for a path. The default list action is read-only; grant, revoke, set, clear, chown, and inheritance changes return a plan unless confirm=true.
- **local_ydb_prepare_auth_config** — Generate a hardened YDB config from the current static-node config. Use before local_ydb_write_dynamic_auth_config and local_ydb_apply_auth_hardening; without confirm=true this returns the planned write only.
- **local_ydb_write_dynamic_auth_config** — Write the text-proto dynamic-node auth token file needed for mandatory-auth startup. Use after choosing the SID for auth hardening; without confirm=true this returns the planned file write only.
- **local_ydb_apply_auth_hardening** — Apply a reviewed hardened YDB config file only after a full check-only static profile and configured-binding compatibility preflight succeeds before any config or container mutation; immutable mismatches require destroy followed by bootstrap. It then restarts the static node and recreates and verif…
- **local_ydb_set_root_password** — 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_complexity; this tool requires a non-empty password value.
- **local_ydb_add_storage_groups** — Increase NumGroups for one tenant storage pool using the current ReadStoragePool definition. Without confirm=true this returns the DefineStoragePool plan, rollback, target pool, and target count; when the update succeeds it verifies NumGroups and tenant metadata.
- **local_ydb_reduce_storage_groups** — Reduce NumGroups for a tenant storage pool by dumping the tenant, rebuilding the profile stack with a smaller storagePoolCount, restoring the dump, and reapplying auth when needed. Before dump or destroy, it inspects every one-off dynamic node and preserves its exact gRPC, monitoring, and IC ports;…
- **local_ydb_cleanup_storage** — Delete only the explicitly supplied local-ydb host paths or Docker volumes. Use after inspecting local_ydb_storage_leftovers; without confirm=true this returns the cleanup plan and removes nothing.
- **local_ydb_pull_image** — Plan or start a background Docker pull for a local-ydb image on the selected target. Without confirm=true it returns inspect and pull commands only; with confirm=true it returns a jobId for local_ydb_pull_status unless the image is already present.
- **local_ydb_destroy_stack** — Remove tenant metadata, local-ydb containers, network, and storage for a profile, with optional host-path cleanup.
- **local_ydb_bootstrap_root_database** — Bootstrap a plain local YDB database at /local with only a static node. Use for generic local database requests that do not need a CMS tenant, GraphShard, or dynamic nodes; an existing running or stopped static container is reused only when its image, network, data mount, complete port bindings, re…
- **local_ydb_bootstrap** — Bootstrap a tenant topology: static node with GraphShard flags and loopback bindings for static plus every configured dynamic gRPC port, configured CMS tenant, and all dynamic nodes declared by profile.dynamicNodeCount. Before returning or executing a plan, configured container names must be distin…
- **local_ydb_check_prerequisites** — Check target-host prerequisites for the Docker CLI and daemon, curl, ruby, and the configured rootPasswordFile when present. An unreachable SSH target returns unavailable=[target] without claiming tools are missing or proposing installation. Without confirm=true it returns the current snapshot and…
- **local_ydb_create_tenant** — Create the configured CMS tenant when the static node is already running. Use before local_ydb_start_dynamic_node for tenant topologies; without confirm=true this returns the planned status/create command and creates nothing.
- **local_ydb_start_dynamic_node** — Start the configured primary dynamic tenant node for an existing CMS tenant. Before returning or executing a plan, it rejects a primary name that aliases the static container and ports that collide in the shared network namespace, including static IC port 19001. After checking that the image is pre…
- **local_ydb_restart_stack** — Reconcile and restart the selected profile after inventory and a full check-only static compatibility preflight. Before stopping any container, require the existing static container to match the profile image, network, data mount, environment, restart policy, healthcheck, and exact loopback binding…
- **local_ydb_upgrade_version** — Upgrade a file-backed, volume-backed local-ydb profile to a target image tag. Use only for version upgrades on profiles without bindMountPath; before dump or destroy it inspects every one-off dynamic node and preserves its exact gRPC, monitoring, and IC ports, aborting on an incomplete definition.…
- **local_ydb_add_dynamic_nodes** — Add one-off dynamic tenant nodes beyond the declarative profile.dynamicNodeCount topology, one at a time. By default the first suffix is dynamicNodeCount + 1; an explicit startIndex must be greater than dynamicNodeCount, and port overrides remain available. Every planned name must be distinct from…
- **local_ydb_remove_dynamic_nodes** — Remove dynamic tenant suffix nodes one at a time and verify nodelist disappearance when the node IC port can be resolved. Without containers, nodeIds, or startIndex, only one-off suffixes above profile.dynamicNodeCount are eligible and the highest suffix is removed first. Explicit selectors or star…
- **local_ydb_list_dumps** — Read-only list of available tenant dumps under profile.dumpHostPath. Use before restore to choose a dumpName; it only reports top-level dump directories that contain the existing tenant dump folder.
- **local_ydb_dump_tenant** — Dump the configured tenant or a tenant-relative path using a local-ydb helper container on the static container network. It creates profile.dumpHostPath/dumpName, excludes .sys objects, writes the dump under dumpName/tenant, and without confirm=true returns the mkdir/helper-container plan only.
- **local_ydb_restore_tenant** — Restore the configured tenant or destination path from a dump under profile.dumpHostPath, with optional post-restore scheme describe and bounded count-query verification. Use after bootstrap or rebuild when the target tenant is ready; without confirm=true this returns the restore plan and does not…

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `LOCAL_YDB_TOOLKIT_CONFIG` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/astandrik-local-ydb-toolkit/readme_