Ydb Mcp

Ydb Mcp

What is Ydb Mcp about?

Ydb Mcp offers a server implementation of the Model Context Protocol (MCP) tailored for YDB. It bridges large language models and YDB instances, allowing AI‑driven database operations such as running SQL queries, exploring directory structures, and obtaining path details.

How to use Ydb Mcp?

1. Install the package via pip install ydb-mcp (or use uvx / pipx).
2. Start the server with a command similar to:

   python3 -m ydb_mcp --ydb-endpoint grpc://localhost:2136 --ydb-database /local
   

3. Configure your MCP client by adding a server entry (see serverConfig).
4. Interact using the provided tools (ydb_query, ydb_list_directory, etc.) either directly through the MCP client or via LLM prompts that invoke these tools.

Key features of Ydb Mcp

• Support for multiple authentication modes (anonymous, login/password, access‑token, service‑account).
• Built‑in tools:
  • ydb_query – execute raw SQL.
  • ydb_query_with_params – run parameterised queries with JSON parameters.
  • ydb_list_directory – list contents of a YDB directory.
  • ydb_describe_path – fetch metadata of tables, directories, etc.
  • ydb_status – report current connection status.
• Flexible installation options (uvx, pipx, pip).
• Development workflow with Makefile targets for testing, linting, formatting, and running the server.

Use cases of Ydb Mcp

• AI‑assisted data analysis: LLMs generate natural‑language queries that are translated into SQL and executed on YDB.
• Automated database administration: Prompt‑driven commands to list directories, describe schemas, or check connection health.
• Developer tooling: Embed YDB operations within chat‑based assistants or IDE plugins without writing boilerplate code.

FAQ from the Ydb Mcp

• Q: Do I need a YDB instance running locally? A: Yes, the server requires an accessible YDB endpoint (default grpc://localhost:2136).
• Q: Which authentication methods are supported? A: Anonymous, login/password, access‑token, and service‑account (via a JSON key file).
• Q: Can I run the server without installing Python globally? A: Use uvx ydb-mcp … or pipx run ydb-mcp … to execute it in an isolated environment.
• Q: How do I integrate with a LLM client? A: Add the server entry to the client’s MCP configuration; the client will call the exposed tools based on the model’s prompts.
• Q: Is there a way to customize server arguments? A: Yes, additional flags can be passed via the ARGS environment variable when using make run-server.

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.

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

To use service account authentication, specify the --ydb-auth-mode and --ydb-sa-key-file arguments:

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "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_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

Development

The project uses Make as its primary development tool, providing a consistent interface for common development tasks.

Available Make Commands

The project includes a comprehensive Makefile with various commands for development tasks. Each command is designed to streamline the development workflow and ensure code quality:

• make all: Run clean, lint, and test in sequence (default target)
• make clean: Remove all build artifacts and temporary files
• make test: Run all tests using pytest
  • Can be configured with environment variables:
    • LOG_LEVEL (default: WARNING) - Control test output verbosity (DEBUG, INFO, WARNING, ERROR)
• make unit-tests: Run only unit tests with verbose output
  • Can be configured with environment variables:
    • LOG_LEVEL (default: WARNING) - Control test output verbosity (DEBUG, INFO, WARNING, ERROR)
• make integration-tests: Run only integration tests with verbose output
  • Can be configured with environment variables:
    • YDB_ENDPOINT (default: grpc://localhost:2136)
    • YDB_DATABASE (default: /local)
    • MCP_HOST (default: 127.0.0.1)
    • MCP_PORT (default: 8989)
    • LOG_LEVEL (default: WARNING) - Control test output verbosity (DEBUG, INFO, WARNING, ERROR)
• make run-server: Start the YDB MCP server
  • Can be configured with environment variables:
    • YDB_ENDPOINT (default: grpc://localhost:2136)
    • YDB_DATABASE (default: /local)
  • Additional arguments can be passed using ARGS="your args"
• make lint: Run all linting checks (flake8, mypy, black, isort)
• make format: Format code using black and isort
• make install: Install the package in development mode
• make dev: Install the package in development mode with all development dependencies

Test Verbosity Control

By default, tests run with minimal output (WARNING level) to keep the output clean. You can control the verbosity of test output using the LOG_LEVEL environment variable:

# Run all tests with debug output
make test LOG_LEVEL=DEBUG

# Run integration tests with info output
make integration-tests LOG_LEVEL=INFO

# Run unit tests with warning output (default)
make unit-tests LOG_LEVEL=WARNING

Available log levels:

• DEBUG: Show all debug messages, useful for detailed test flow
• INFO: Show informational messages and above
• WARNING: Show only warnings and errors (default)
• ERROR: Show only error messages