Skip to content

Commit be1591e

Browse files
blinkovanton-bobkov
blinkov
and
anton-bobkov
committed
Co-authored-by: anton-bobkov <anton-bobkov@yandex-team.ru>
1 parent e8210ef commit be1591e

File tree

8 files changed

+420
-12
lines changed

8 files changed

+420
-12
lines changed

‎ydb/docs/en/core/reference/languages-and-apis/index.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# Languages and APIs
22

3+
- [{#T}](ado-net/index.md)
34
- [{#T}](jdbc-driver/index.md)
4-
- [{#T}](ado-net/index.md)
5+
- [{#T}](mcp/index.md)

‎ydb/docs/en/core/reference/languages-and-apis/mcp/_assets/example-usage.png

147 KB
Loading

‎ydb/docs/en/core/reference/languages-and-apis/mcp/index.md

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# {{ ydb-short-name }} Model Context Protocol Server
2+
3+
[{{ ydb-short-name }} Model Context Protocol (MCP) server](https://github.com/ydb-platform/ydb-mcp) allows you to work with {{ ydb-short-name }} databases from any [Large Language Model (LLM)](https://en.wikipedia.org/wiki/Large_language_model) that supports [MCP](https://modelcontextprotocol.io/introduction) using any of the [MCP clients](https://modelcontextprotocol.io/clients). This integration enables AI-powered database operations and natural language interactions with your {{ ydb-short-name }} instances.
4+
5+
## Getting Started
6+
7+
### Prerequisites
8+
9+
1. Install an [MCP client](https://modelcontextprotocol.io/clients) that supports MCP tools (most do). The configuration examples below use a common format supported by several popular MCP clients (Claude Desktop, Cursor, etc.), but you may need to adjust the format to meet your client's requirements.
10+
2. The {{ ydb-short-name }} MCP server is a Python application that is typically co-hosted with the MCP client. There are several options for installing and running the {{ ydb-short-name }} MCP server [explained below](#server-arguments), but all of them require a pre-installed Python 3.10+ environment.
11+
12+
### Anonymous Authentication
13+
14+
{% list tabs tab group=install %}
15+
16+
- uvx
17+
18+
[uvx](https://docs.astral.sh/uv/guides/tools/) allows you to run Python applications without explicitly installing them.
19+
20+
Configure {{ ydb-short-name }} MCP in your MCP client settings:
21+
22+
```json
23+
{
24+
"mcpServers": {
25+
"ydb": {
26+
"command": "uvx",
27+
"args": [
28+
"ydb-mcp",
29+
"--ydb-endpoint", "grpc://localhost:2136/local"
30+
]
31+
}
32+
}
33+
}
34+
```
35+
36+
- pipx
37+
38+
[pipx](https://pipx.pypa.io/stable/installation/) allows you to run applications from PyPI without explicit installation (pipx itself must be installed first).
39+
40+
Configure {{ ydb-short-name }} MCP in your MCP client settings:
41+
42+
```json
43+
{
44+
"mcpServers": {
45+
"ydb": {
46+
"command": "pipx",
47+
"args": [
48+
"run", "ydb-mcp",
49+
"--ydb-endpoint", "grpc://localhost:2136/local"
50+
]
51+
}
52+
}
53+
}
54+
```
55+
56+
- pip
57+
58+
Optionally, create and activate a [Python virtual environment](https://docs.python.org/3/library/venv.html). Install {{ ydb-short-name }} MCP using [pip](https://pypi.org/project/pip/):
59+
60+
```bash
61+
pip install ydb-mcp
62+
```
63+
64+
Configure {{ ydb-short-name }} MCP in your MCP client settings:
65+
66+
```json
67+
{
68+
"mcpServers": {
69+
"ydb": {
70+
"command": "python3",
71+
"args": [
72+
"-m", "ydb_mcp",
73+
"--ydb-endpoint", "grpc://localhost:2136/local"
74+
]
75+
}
76+
}
77+
}
78+
```
79+
80+
{% endlist %}
81+
82+
## Login-Password Authentication
83+
84+
{% list tabs group=install %}
85+
86+
- uvx
87+
88+
Configure login/password authentication with `uvx`:
89+
90+
```json
91+
{
92+
"mcpServers": {
93+
"ydb": {
94+
"command": "uvx",
95+
"args": [
96+
"ydb-mcp",
97+
"--ydb-endpoint", "grpc://localhost:2136/local",
98+
"--ydb-auth-mode", "login-password",
99+
"--ydb-login", "<your-username>",
100+
"--ydb-password", "<your-password>"
101+
]
102+
}
103+
}
104+
}
105+
```
106+
107+
- pipx
108+
109+
Configure login/password authentication with `pipx`:
110+
111+
```json
112+
{
113+
"mcpServers": {
114+
"ydb": {
115+
"command": "pipx",
116+
"args": [
117+
"run", "ydb-mcp",
118+
"--ydb-endpoint", "grpc://localhost:2136/local",
119+
"--ydb-auth-mode", "login-password",
120+
"--ydb-login", "<your-username>",
121+
"--ydb-password", "<your-password>"
122+
]
123+
}
124+
}
125+
}
126+
```
127+
128+
- pip
129+
130+
Configure login/password authentication with `pip`-installed {{ ydb-short-name }} MCP:
131+
132+
```json
133+
{
134+
"mcpServers": {
135+
"ydb": {
136+
"command": "python3",
137+
"args": [
138+
"-m", "ydb_mcp",
139+
"--ydb-endpoint", "grpc://localhost:2136/local",
140+
"--ydb-auth-mode", "login-password",
141+
"--ydb-login", "<your-username>",
142+
"--ydb-password", "<your-password>"
143+
]
144+
}
145+
}
146+
}
147+
```
148+
149+
{% endlist %}
150+
151+
### Run Queries
152+
153+
Ask your LLM questions regarding the data stored in {{ ydb-short-name }} using the MCP client configured above. The language model will see the tools available to it via MCP and will use them to execute [YQL](../../../yql/reference/index.md) queries and other {{ ydb-short-name }} API calls. An example of how it might look:
154+
155+
![Example usage of YDB MCP server](_assets/example-usage.png)
156+
157+
## Available Tools
158+
159+
{{ ydb-short-name }} MCP provides the following tools for interacting with {{ ydb-short-name }} databases:
160+
161+
* `ydb_query`: Run a SQL query against a {{ ydb-short-name }} database
162+
* Parameters:
163+
* `sql`: SQL query string to execute
164+
165+
* `ydb_query_with_params`: Run a parameterized SQL query with JSON parameters
166+
* Parameters:
167+
* `sql`: SQL query string with parameters
168+
* `params`: JSON string containing parameter values
169+
170+
* `ydb_list_directory`: List directory contents in {{ ydb-short-name }}
171+
* Parameters:
172+
* `path`: YDB directory path to list
173+
174+
* `ydb_describe_path`: Get detailed information about a [scheme object](../../../concepts/glossary.md#scheme-object) (table, directory, etc) located at the specified {{ ydb-short-name }} path
175+
* Parameters:
176+
* `path`: {{ ydb-short-name }} path to describe
177+
178+
* `ydb_status`: Get the current status of the {{ ydb-short-name }} connection
179+
180+
## Command-line arguments and environment variables {#server-arguments}
181+
182+
The following table describes the command-line arguments and environment variables for the {{ ydb-short-name }} MCP server:
183+
184+
| Arguments | Environment variable | Default | Description |
185+
| --------------------- | -------------------- | ------------------------ | ------------------------------------------------------------------------------------------- |
186+
| `--ydb-endpoint` | `YDB_ENDPOINT` | — | {{ ydb-short-name }} endpoint consisting of protocol, hostname, port, and database name |
187+
| `--ydb-login` | `YDB_LOGIN` | — | {{ ydb-short-name }} login |
188+
| `--ydb-password` | `YDB_PASSWORD` | — | {{ ydb-short-name }} password |
189+
| `--ydb-auth-mode` | `YDB_AUTH_MODE` | `anonymous` | {{ ydb-short-name }} authentication mode. Valid values: `anonymous`, `login-password` |
190+
| `--log-level` | — | `INFO` | Logging level. Valid values: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
191+
192+
{% note info %}
193+
194+
Command-line arguments override the corresponding environment variables.
195+
196+
{% endnote %}
197+
198+
## Learn More
199+
200+
For more information visit the [{{ ydb-short-name }} MCP GitHub repository](https://github.com/ydb-platform/ydb-mcp).

‎ydb/docs/en/core/reference/languages-and-apis/toc_p.yaml

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
items:
2-
- name: JDBC driver
3-
href: jdbc-driver/index.md
4-
include:
5-
mode: link
6-
path: jdbc-driver/toc_p.yaml
72
- name: ADO.NET
83
href: ado-net/index.md
94
include:
105
mode: link
116
path: ado-net/toc_p.yaml
7+
- name: JDBC driver
8+
href: jdbc-driver/index.md
9+
include:
10+
mode: link
11+
path: jdbc-driver/toc_p.yaml
12+
- name: Model Context Protocol
13+
href: mcp/index.md

‎ydb/docs/ru/core/reference/languages-and-apis/index.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# Языки и API
22

3+
- [{#T}](ado-net/index.md)
34
- [{#T}](jdbc-driver/index.md)
4-
- [{#T}](ado-net/index.md)
5+
- [{#T}](mcp/index.md)

‎ydb/docs/ru/core/reference/languages-and-apis/mcp/_assets/example-usage.png

147 KB
Loading

0 commit comments

Comments
 (0)