# Local YDB MCP

> Local YDB MCP is an open-source MCP server for databases. Operate Docker-based local YDB stacks from an agent, with plan-first changes and confirm. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, Linux, macOS
- **Website:** https://local-ydb-toolkit.ydb-qdrant.tech
- **Repository:** https://github.com/astandrik/local-ydb-toolkit/tree/HEAD/packages/mcp-server
- **MCP Registry name:** io.github.astandrik/local-ydb-mcp
- **Categories:** databases, cloud and infrastructure
- **Listing updated:** 2026-11-14

## About

This stdio server is for agents that need to run the local-ydb environment itself, not just query a database. The README places it beside the official ydb-platform/ydb-mcp: that server handles ad hoc SQL, query explanations and path inspection against an existing YDB endpoint, while this one covers host prerequisite checks, root or tenant bootstrap, health diagnostics, dynamic-node lifecycle, GraphShard checks, table DDL generation and validation, auth hardening, storage workflows, dump and restore, and version upgrades.

Anything that changes state returns a plan first and executes only when confirm: true is supplied. Its local_ydb_sql tool is deliberately narrower than the official one and runs managed YQL only against the selected configured profile. Intentional upgrades go through local_ydb_upgrade_version, which dumps and rebuilds the stack. A JSON config file, optionally pointed to by LOCAL_YDB_TOOLKIT_CONFIG, defines profiles; without one a default profile using a local-ydb image is used, and the README advises pinning the image explicitly.

Private config files, SSH settings, password files and database credentials stay on the machine or CI runner. It needs Node.js 20.19 or newer, can work locally or over SSH, and is described as unofficial. A companion Codex skill and a GitHub Action for disposable YDB in CI are published by the same project.

## Features

- **Plan-first changes:** Mutating tools return a plan and run only with confirm: true.
- **Stack lifecycle:** Bootstrap root or tenant stacks, manage dynamic nodes and check health.
- **Managed YQL:** local_ydb_sql runs YQL against the selected local profile only.
- **Dump and upgrade:** Dump, restore and rebuild a stack for version upgrades.
- **Local credentials:** Config, SSH settings and password files never leave your machine.

## Good for

- Bootstrap a disposable YDB for development
- Diagnose why a local database is unhealthy
- Apply table DDL to a local deployment
- Harden authentication on a local stack
- Upgrade a stack to a newer image by dump and rebuild

## Install

### Claude Code (Terminal)

```sh
claude mcp add local-ydb-mcp -- npx -y @astandrik/local-ydb-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "local-ydb-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@astandrik/local-ydb-mcp"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "local-ydb-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@astandrik/local-ydb-mcp"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "local-ydb-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@astandrik/local-ydb-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "local-ydb-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@astandrik/local-ydb-mcp"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "local-ydb-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@astandrik/local-ydb-mcp"
      ]
    }
  }
}
```

## Tools

- `local_ydb_sql`: Run managed YQL against the selected local-ydb profile.
- `local_ydb_upgrade_version`: Upgrade a stack by dump and rebuild.

## FAQ

### Does it replace the official YDB MCP server?

No. The README calls it complementary: use the official one for general database queries and this one to operate local-ydb stacks.

### What does it need?

Node.js 20.19 or newer and, for real operations, Docker or SSH access where local-ydb runs.

### Can it change things without confirmation?

Mutating tools return a plan first and execute only when confirm: true is provided.

### Where is configuration read from?

LOCAL_YDB_TOOLKIT_CONFIG if set, otherwise local-ydb.config.json in the working directory.

### Is Local YDB MCP free?

Yes. Local YDB MCP is open source, so you can use and self-host it for free.

### How do I add Local YDB MCP to Claude Code?

Run this command in your terminal: claude mcp add local-ydb-mcp -- npx -y @astandrik/local-ydb-mcp

### What are the best alternatives to Local YDB MCP?

The closest alternatives to Local YDB MCP are Midplane, Agent Yurt, Proofline, filex and MagicWP MCP.

## Alternatives

- [Midplane](https://ai-powered.com/mcp/midplane): Midplane is an open-source MCP server for databases.
- [Agent Yurt](https://ai-powered.com/mcp/agent-yurt): Agent Yurt is a free MCP server for knowledge and memory.
- [Proofline](https://ai-powered.com/mcp/proofline): Proofline is a freemium MCP server for developer tools.
- [filex](https://ai-powered.com/mcp/filex): filex is an open-source MCP server for files and documents.
- [MagicWP MCP](https://ai-powered.com/mcp/magicwp-mcp): MagicWP MCP is an MCP server for cloud and infrastructure.
- [Kubana Cloud DNS Management](https://ai-powered.com/mcp/kubana-cloud-dns-management): Kubana Cloud DNS Management is a free MCP server for cloud and infrastructure.
- [AgentViva](https://ai-powered.com/mcp/agentviva): AgentViva is a free MCP server for developer tools.
- [Kubana Cloud Webmail](https://ai-powered.com/mcp/kubana-cloud-webmail): Kubana Cloud Webmail is a paid MCP server for communication.

---
Source: https://ai-powered.com/mcp/local-ydb-mcp
