How to add YDB MCP to Windsurf

Query and explore YDB databases from any MCP-compatible LLM using natural language. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 27★ · stdio · apikey

Windsurf config for YDB MCP

pip install ydb-mcp

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

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the YDB MCP config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5YDB MCP's tools become available to Cascade.

Before you start

A reachable YDB endpoint and database (e.g. grpc://localhost:2136 with database /local)
Python 3 with one of uvx (uv), pipx, or pip available to launch the server
Valid YDB credentials for the chosen auth mode (login/password, access token, or service-account key file); the yandexcloud package is also required for service-account auth

What YDB MCP can do in Windsurf

ydb_query

Run a SQL query against a YDB database. Parameter: sql (SQL query string to execute).

ydb_query_with_params

Run a parameterized SQL query with JSON parameters. Parameters: sql (query with placeholders), params (JSON string of parameter values).

ydb_explain_query

Explain a SQL query, returning the execution plan. Parameter: sql (SQL query string to explain).

ydb_explain_query_with_params

Explain a parameterized SQL query. Parameters: sql (query with placeholders), params (JSON string of parameter values).

ydb_list_directory

List directory contents in YDB. Parameter: path (YDB directory path to list).

ydb_describe_path

Get detailed information about a YDB path such as a table or directory. Parameter: path (YDB path to describe).

ydb_status

Get the current status of the YDB connection.

Security

The ydb_query and ydb_query_with_params tools execute arbitrary SQL against the connected YDB database, so the configured credentials should be scoped to the minimum privileges needed. Credentials (login/password, access token, or service-account key file) are passed as command-line arguments in the MCP client config; access-token and password values appear in plaintext in that config. For restricted deployments, subclass YDBMCPServer to disable generic tools and expose only fixed, read-only queries.

YDB MCP + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the YDB MCP config there under the "mcpServers" key and restart the client.

Is YDB MCP safe to use with Windsurf?

How do I run YDB MCP without installing it?

Use uvx (an alias for uv run tool) or pipx run, pointing the command at ydb-mcp with --ydb-endpoint and --ydb-database arguments. Both let you launch the server without a persistent install.

Which authentication modes are supported?

Anonymous (default), login/password (--ydb-auth-mode login-password with --ydb-login/--ydb-password), access token (--ydb-auth-mode access-token with --ydb-access-token), and Yandex Cloud service account (--ydb-auth-mode service-account with --ydb-sa-key-file, which also requires the yandexcloud package).

Can I limit which tools the model can use?

Yes. Subclass YDBMCPServer and set the generic_tools class attribute to a subset of the YDBGenericTool enum (or an empty set), then register your own @self.tool() functions. This lets you expose only fixed, read-only queries instead of arbitrary SQL execution.

View repo Full YDB MCP page