YDB

You can run the YDB MCP Server to connect your YDB databases with any MCP-enabled client. It enables AI-powered database interactions, allowing you to execute SQL, list paths, describe objects, and check status from an MCP-compliant toolchain.

How to use

To use the YDB MCP Server, choose a local runner that suits your workflow (uvx, pipx, or plain pip with Python). Each option starts the MCP server by invoking the ydb-mcp package and passes the YDB endpoint and database path. You can switch between anonymous authentication and different credentials by adding the appropriate authentication flags when you start the server.

How to install

Prerequisites: You need Python 3.8+ and a working Internet connection. You may also use uvx, pipx, or pip to run the MCP server.

Install the MCP package with pip.

pip install ydb-mcp

Optionally, you can run the MCP server without installing it system-wide by using uvx or pipx. Use one of the following configurations in your MCP client to connect to the YDB MCP server.

Configure the MCP client to start the server locally with anonymous authentication using uvx, pipx, or Python.

{
  "mcpServers": {
    "ydb_uvx": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local"
      ]
    }
  }
}

Additional configuration and authentication

You can enable different authentication methods by adding specific flags when you start the MCP server. The following options are demonstrated for anonymous, login/password, access token, and service account authentication.

{
  "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>"
      ]
    }
  }
}

Notes on running with different runners

If you prefer a different runner, adapt the command and arguments accordingly. The same endpoint and database options apply across uvx, pipx, and python-based invocations. Remember to keep credentials secure and avoid exposing them in shared configurations.

Security considerations

Handle authentication details with care. Use strong credentials for login/password, rotate access tokens regularly, and protect service account keys. When using tokens or keys, store them in secure env vars or secret management systems and avoid embedding them in plain text configuration files.

Troubleshooting

If the MCP server fails to start, verify that the endpoint and database path are correct and that the YDB instance is reachable at grpc://localhost:2136. Check that the required authentication flags are valid and that your chosen runner has the necessary permissions to execute the ydb-mcp package.

Examples of common configurations

The following configurations illustrate anonymous authentication using different runners. You can adapt them to include specific YDB endpoints or databases as needed.

{
  "mcpServers": {
    "ydb_uvx": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local"
      ]
    },
    "ydb_pipx": {
      "command": "pipx",
      "args": [
        "run", "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local"
      ]
    },
    "ydb_pip": {
      "command": "python3",
      "args": [
        "-m", "ydb_mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local"
      ]
    }
  }
}

What you can do with the MCP server

Once running, you can issue SQL queries, list directory contents, describe paths, and query the status of the YDB connection via MCP-enabled clients.

Available tools

ydb_query

Run a SQL query against a YDB database.

ydb_query_with_params

Run a parameterized SQL query with JSON parameters.

ydb_list_directory

List directory contents in YDB.

ydb_describe_path

Get detailed information about a YDB path.

ydb_status

Get the current status of the YDB connection.