YDB MCP

1# YDB MCP
2---
3[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/ydb-platform/ydb-mcp/blob/main/LICENSE)
4[![PyPI version](https://badge.fury.io/py/ydb-mcp.svg)](https://badge.fury.io/py/ydb-mcp)
5 
6[Model Context Protocol server](https://modelcontextprotocol.io/) for [YDB](https://ydb.tech). It allows to work with YDB databases from any [LLM](https://en.wikipedia.org/wiki/Large_language_model) that supports MCP. This integration enables AI-powered database operations and natural language interactions with your YDB instances.
7 
8<a href="https://glama.ai/mcp/servers/@ydb-platform/ydb-mcp">
9  <img width="380" height="200" src="https://glama.ai/mcp/servers/@ydb-platform/ydb-mcp/badge" alt="YDB MCP server" />
10</a>
11 
12## Usage
13 
14### Via uvx
15 
16[uvx](https://docs.astral.sh/uv/concepts/tools/), 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`.
17 
18#### Example: Using Anonymous Authentication
19 
20```json
21{
22  "mcpServers": {
23    "ydb": {
24      "command": "uvx",
25      "args": [
26        "ydb-mcp",
27        "--ydb-endpoint", "grpc://localhost:2136",
28        "--ydb-database", "/local"
29      ]
30    }
31  }
32}
33```
34 
35### Via pipx
36 
37[pipx](https://pipx.pypa.io/stable/) allows you to run various applications from PyPI without explicitly installing each one. However, it must be [installed](https://pipx.pypa.io/stable/#install-pipx) first. Below are examples of how to configure YDB MCP using `pipx`.
38 
39#### Example: Using Anonymous Authentication
40 
41```json
42{
43  "mcpServers": {
44    "ydb": {
45      "command": "pipx",
46      "args": [
47        "run", "ydb-mcp",
48        "--ydb-endpoint", "grpc://localhost:2136",
49        "--ydb-database", "/local"
50      ]
51    }
52  }
53}
54```
55 
56### Via pip
57 
58YDB MCP can be installed using `pip`, [Python's package installer](https://pypi.org/project/pip/). The package is [available on PyPI](https://pypi.org/project/ydb-mcp/) and includes all necessary dependencies.
59 
60```bash
61pip install ydb-mcp
62```
63 
64To 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.
65 
66#### Example: Using Anonymous Authentication
67 
68```json
69{
70  "mcpServers": {
71    "ydb": {
72      "command": "python3",
73      "args": [
74        "-m", "ydb_mcp",
75        "--ydb-endpoint", "grpc://localhost:2136",
76        "--ydb-database", "/local"
77      ]
78    }
79  }
80}
81```
82 
83### Authentication
84 
85Regardless of the usage method (`uvx`, `pipx` or `pip`), you can configure authentication for your YDB installation. To do this, pass special command line arguments.
86 
87#### Using Login/Password Authentication
88 
89To use login/password authentication, specify the `--ydb-auth-mode`, `--ydb-login`, and `--ydb-password` arguments:
90 
91```json
92{
93  "mcpServers": {
94    "ydb": {
95      "command": "uvx",
96      "args": [
97        "ydb-mcp",
98        "--ydb-endpoint", "grpc://localhost:2136",
99        "--ydb-database", "/local",
100        "--ydb-auth-mode", "login-password",
101        "--ydb-login", "<your-username>",
102        "--ydb-password", "<your-password>"
103      ]
104    }
105  }
106}
107```
108 
109#### Using Access Token Authentication
110 
111To use access token authentication, specify the `--ydb-auth-mode` and `--ydb-access-token` arguments:
112 
113```json
114{
115  "mcpServers": {
116    "ydb": {
117      "command": "uvx",
118      "args": [
119        "ydb-mcp",
120        "--ydb-endpoint", "grpc://localhost:2136",
121        "--ydb-database", "/local",
122        "--ydb-auth-mode", "access-token",
123        "--ydb-access-token", "qwerty123"
124      ]
125    }
126  }
127}
128```
129 
130#### Using Service Account Authentication
131 
132To use service account authentication, specify the `--ydb-auth-mode` and `--ydb-sa-key-file` arguments:
133 
134```json
135{
136  "mcpServers": {
137    "ydb": {
138      "command": "uvx",
139      "args": [
140        "ydb-mcp",
141        "--ydb-endpoint", "grpc://localhost:2136",
142        "--ydb-database", "/local",
143        "--ydb-auth-mode", "service-account",
144        "--ydb-sa-key-file", "~/sa_key.json"
145      ]
146    }
147  }
148}
149```
150 
151## Available Tools
152 
153YDB MCP provides the following tools for interacting with YDB databases:
154 
155- `ydb_query`: Run a SQL query against a YDB database
156  - Parameters:
157    - `sql`: SQL query string to execute
158 
159- `ydb_query_with_params`: Run a parameterized SQL query with JSON parameters
160  - Parameters:
161    - `sql`: SQL query string with parameter placeholders
162    - `params`: JSON string containing parameter values
163 
164- `ydb_list_directory`: List directory contents in YDB
165  - Parameters:
166    - `path`: YDB directory path to list
167 
168- `ydb_describe_path`: Get detailed information about a YDB path (table, directory, etc.)
169  - Parameters:
170    - `path`: YDB path to describe
171 
172- `ydb_status`: Get the current status of the YDB connection
173 
174## Development
175 
176The project uses [Make](https://www.gnu.org/software/make/) as its primary development tool, providing a consistent interface for common development tasks.
177 
178### Available Make Commands
179 
180The project includes a comprehensive Makefile with various commands for development tasks. Each command is designed to streamline the development workflow and ensure code quality:
181 
182- `make all`: Run clean, lint, and test in sequence (default target)
183- `make clean`: Remove all build artifacts and temporary files
184- `make test`: Run all tests using pytest
185  - Can be configured with environment variables:
186    - `LOG_LEVEL` (default: WARNING) - Control test output verbosity (DEBUG, INFO, WARNING, ERROR)
187- `make unit-tests`: Run only unit tests with verbose output
188  - Can be configured with environment variables:
189    - `LOG_LEVEL` (default: WARNING) - Control test output verbosity (DEBUG, INFO, WARNING, ERROR)
190- `make integration-tests`: Run only integration tests with verbose output
191  - Can be configured with environment variables:
192    - `YDB_ENDPOINT` (default: grpc://localhost:2136)
193    - `YDB_DATABASE` (default: /local)
194    - `MCP_HOST` (default: 127.0.0.1)
195    - `MCP_PORT` (default: 8989)
196    - `LOG_LEVEL` (default: WARNING) - Control test output verbosity (DEBUG, INFO, WARNING, ERROR)
197- `make run-server`: Start the YDB MCP server
198  - Can be configured with environment variables:
199    - `YDB_ENDPOINT` (default: grpc://localhost:2136)
200    - `YDB_DATABASE` (default: /local)
201  - Additional arguments can be passed using `ARGS="your args"`
202- `make lint`: Run all linting checks (flake8, mypy, black, isort)
203- `make format`: Format code using black and isort
204- `make install`: Install the package in development mode
205- `make dev`: Install the package in development mode with all development dependencies
206 
207### Test Verbosity Control
208 
209By 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:
210 
211```bash
212# Run all tests with debug output
213make test LOG_LEVEL=DEBUG
214 
215# Run integration tests with info output
216make integration-tests LOG_LEVEL=INFO
217 
218# Run unit tests with warning output (default)
219make unit-tests LOG_LEVEL=WARNING
220```
221 
222Available log levels:
223- `DEBUG`: Show all debug messages, useful for detailed test flow
224- `INFO`: Show informational messages and above
225- `WARNING`: Show only warnings and errors (default)
226- `ERROR`: Show only error messages