# SQL MCP Сервер
MCP (Model Context Protocol) сервер для выполнения запросов к базам данных на естественном языке. Поддерживает SQLite, MySQL, PostgreSQL и MongoDB.
## Возможности
- **Запросы на естественном языке**: Пишите запросы к БД на русском языке
- **Поддержка нескольких БД**: SQLite, MySQL, PostgreSQL, MongoDB
- **MCP протокол**: Stdio-коммуникация с LLM клиентами
- **Интеграция с LLM**: Включает промпты для помощи LLM в использовании сервера
- **SQL операции**: SELECT, INSERT, UPDATE, DELETE, ALTER, CREATE DATABASE
- **Bulk операции**: Множественные INSERT, UPDATE, DELETE за один запрос
- **Просмотр схемы**: Список таблиц и структура таблиц
- **Защита данных**: UPDATE, DELETE, DROP и ALTER требуют явного подтверждения пользователя
- **Пакетные операции**: Одно подтверждение для нескольких изменяющих операций
## Установка
1. **Клонируйте репозиторий:**
```bash
git clone https://github.com/Processori7/SQL-MCP.git
cd SQL-MCP
```
2. **Создайте и активируйте виртуальное окружение (рекомендуется):**
```bash
# Windows
python -m venv venv
venv\Scripts\activate
# Linux/macOS
python3 -m venv venv
source venv/bin/activate
```
3. **Установите зависимости:**
```bash
pip install -r requirements.txt
```
## Интеграция с MCP
### Настройка MCP клиента
Добавьте в конфигурацию вашего MCP клиента (например, `cline_mcp_settings.json`):
```json
{
"mcpServers": {
"sql-stdio": {
"disabled": false,
"timeout": 60,
"type": "stdio",
"command": "python",
"args": ["-X", "utf8", "-m", "src.main"],
"env": {
"PYTHONPATH": "C:\\path\\to\\SQL-MCP",
"PYTHONIOENCODING": "utf-8"
}
}
}
}
```
**Примечание:** Замените `C:\\path\\to\\SQL-MCP` на реальный путь к папке проекта.
**Важно для Windows:** Флаг `-X utf8` и переменная `PYTHONIOENCODING` обеспечивают корректную работу с кириллицей.
## Доступные инструменты
### 1. execute_query
Выполняет запросы к базе данных на естественном языке или SQL.
**Параметры:**
- `db_type` (обязательный): Тип БД - `'sqlite'`, `'mysql'`, `'postgresql'` или `'mongodb'`
- `query` (обязательный): Запрос на русском языке ИЛИ SQL/MongoDB запрос
- `db_config` или `config_file` (один из них обязателен): Настройки подключения к БД
- `confirm_changes` (опциональный): Подтверждение для операций изменения/удаления данных
### 2. list_tables
Получает список всех таблиц или коллекций в базе данных.
**Параметры:**
- `db_type` (обязательный): Тип базы данных
- `db_config` или `config_file` (один из них обязателен): Настройки подключения к БД
### 3. get_table_schema
Получает схему таблицы (колонки, типы, ограничения).
**Параметры:**
- `db_type` (обязательный): Тип БД (не поддерживается для MongoDB)
- `table_name` (обязательный): Имя таблицы
- `db_config` или `config_file` (один из них обязателен): Настройки подключения к БД
## Примеры использования
### Конфигурации подключения
Есть два способа указать параметры подключения:
#### Способ 1: Параметр db_config (JSON объект)
##### MySQL
```json
{
"host": "localhost",
"port": 3306,
"user": "root",
"password": "mypassword",
"database": "mydb"
}
```
##### PostgreSQL
```json
{
"host": "localhost",
"port": 5432,
"user": "postgres",
"password": "mypassword",
"dbname": "mydb"
}
```
##### SQLite
```json
{
"db_name": "mydata.db"
}
```
##### MongoDB
```json
{
"uri": "mongodb://localhost:27017",
"database_name": "mydb"
}
```
#### Способ 2: Параметр config_file (путь к файлу)
Укажите путь к файлу конфигурации. Поддерживаются форматы JSON и TXT.
**Пример JSON файла (mysql_config.json):**
```json
{
"host": "localhost",
"port": 3306,
"user": "root",
"password": "mypassword",
"database": "mydb"
}
```
**Пример TXT файла (mysql_config.txt):**
```ini
# Конфигурация MySQL
host=localhost
port=3306
user=root
password=mypassword
database=mydb
```
**Использование config_file:**
```json
{
"db_type": "mysql",
"query": "SELECT * FROM users",
"config_file": "C:/configs/mysql_config.json"
}
```
Или с относительным путём:
```json
{
"db_type": "mysql",
"query": "SHOW TABLES",
"config_file": "mysql_config.txt"
}
```
### Примеры запросов
#### Создание базы данных (MySQL/PostgreSQL)
```json
{
"db_type": "mysql",
"query": "CREATE DATABASE my_new_db",
"db_config": {"host": "localhost", "port": 3306, "user": "root", "password": ""}
}
```
Или на естественном языке:
```json
{
"db_type": "mysql",
"query": "Создай БД my_new_db",
"db_config": {"host": "localhost", "port": 3306, "user": "root", "password": ""}
}
```
#### Переключение базы данных
```json
{
"db_type": "mysql",
"query": "USE my_new_db",
"db_config": {"host": "localhost", "port": 3306, "user": "root", "password": "", "database": "my_new_db"}
}
```
#### Создание таблицы
```json
{
"db_type": "mysql",
"query": "CREATE TABLE users (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(100), email VARCHAR(100), age INT)",
"db_config": {"host": "localhost", "port": 3306, "user": "root", "password": "", "database": "my_new_db"}
}
```
#### Bulk INSERT (множественная вставка)
```json
{
"db_type": "mysql",
"query": "INSERT INTO users (name, email, age) VALUES ('Иван', 'ivan@mail.ru', 25), ('Мария', 'maria@mail.ru', 30), ('Алексей', 'alex@mail.ru', 28)",
"db_config": {"host": "localhost", "port": 3306, "user": "root", "password": "", "database": "my_new_db"}
}
```
#### SELECT с условиями
```json
{
"db_type": "mysql",
"query": "SELECT * FROM users WHERE age > 25",
"db_config": {"host": "localhost", "port": 3306, "user": "root", "password": "", "database": "my_new_db"}
}
```
Или на естественном языке:
```json
{
"db_type": "mysql",
"query": "Покажи всех пользователей где возраст больше 25",
"db_config": {"host": "localhost", "port": 3306, "user": "root", "password": "", "database": "my_new_db"}
}
```
#### Bulk UPDATE (множественное обновление)
```json
{
"db_type": "mysql",
"query": "UPDATE users SET status='active' WHERE id IN (1, 2, 3)",
"db_config": {"host": "localhost", "port": 3306, "user": "root", "password": "", "database": "my_new_db"},
"confirm_changes": true
}
```
#### Bulk DELETE (множественное удаление)
```json
{
"db_type": "mysql",
"query": "DELETE FROM users WHERE status='inactive'",
"db_config": {"host": "localhost", "port": 3306, "user": "root", "password": "", "database": "my_new_db"},
"confirm_changes": true
}
```
### Примеры для MongoDB
#### Поиск документов
```json
{
"db_type": "mongodb",
"query": "db.users.find({age: {$gt: 25}})",
"db_config": {"uri": "mongodb://localhost:27017", "database_name": "mydb"}
}
```
#### Bulk INSERT (insertMany)
```json
{
"db_type": "mongodb",
"query": "db.users.insertMany([{name: 'Иван', age: 25}, {name: 'Мария', age: 30}, {name: 'Алексей', age: 28}])",
"db_config": {"uri": "mongodb://localhost:27017", "database_name": "mydb"}
}
```
#### Bulk UPDATE (updateMany)
```json
{
"db_type": "mongodb",
"query": "db.users.updateMany({status: 'pending'}, {$set: {status: 'active'}})",
"db_config": {"uri": "mongodb://localhost:27017", "database_name": "mydb"},
"confirm_changes": true
}
```
#### Bulk DELETE (deleteMany)
```json
{
"db_type": "mongodb",
"query": "db.users.deleteMany({status: 'inactive'})",
"db_config": {"uri": "mongodb://localhost:27017", "database_name": "mydb"},
"confirm_changes": true
}
```
#### findOneAndUpdate
```json
{
"db_type": "mongodb",
"query": "db.users.findOneAndUpdate({\"_id\": {\"$oid\": \"692c2012253e01f8b4ac2b23\"}}, {\"$set\": {\"name\": \"Новое имя\"}}, {\"returnNewDocument\": true})",
"db_config": {"uri": "mongodb://localhost:27017", "database_name": "mydb"},
"confirm_changes": true
}
```
### Запросы на естественном языке
#### SELECT
- `"Покажи все пользователи"` → SELECT * FROM users
- `"Покажи имя и email из users"` → SELECT name, email FROM users
- `"все сотрудники где возраст больше 30"` → SELECT * FROM сотрудники WHERE возраст > 30
- `"Покажи первые 10 записей из orders"` → SELECT * FROM orders LIMIT 10
#### INSERT
- `"Добавь пользователя имя Иван возраст 25"` → INSERT INTO users (имя, возраст) VALUES ('Иван', 25)
- `"Вставь в таблицу orders запись: товар Ноутбук, цена 50000"` → INSERT INTO orders (товар, цена) VALUES ('Ноутбук', 50000)
#### UPDATE
- `"Обнови в users где id=5 установи name Пётр"` → UPDATE users SET name='Пётр' WHERE id=5
- `"Измени статус на active где id 10"` → UPDATE ... SET статус='active' WHERE id=10
#### DELETE
- `"Удали из users где id=5"` → DELETE FROM users WHERE id=5
- `"Удали все записи из orders где статус cancelled"` → DELETE FROM orders WHERE статус='cancelled'
#### CREATE/DROP
- `"Создай таблицу products с колонками: id INT PRIMARY KEY, name VARCHAR(100)"` → CREATE TABLE products (...)
- `"Создай БД new_database"` → CREATE DATABASE new_database
- `"Удали таблицу old_data"` → DROP TABLE old_data
## Защита данных
Операции, изменяющие данные, **блокируются по умолчанию** и требуют явного подтверждения:
- `UPDATE` - изменение данных
- `DELETE` - удаление данных
- `DROP` - удаление таблиц/коллекций
- `ALTER` - изменение структуры
Для выполнения этих операций LLM должен:
1. Получить ответ `"status": "blocked"`
2. Спросить пользователя о подтверждении
3. После подтверждения повторить запрос с `confirm_changes: true`
## Конвертация SQL в MongoDB
Сервер автоматически конвертирует SQL запросы в MongoDB операции:
| SQL запрос | MongoDB эквивалент |
|-----------|-------------------|
| `SELECT * FROM users` | `db.users.find({})` |
| `SELECT * FROM users WHERE id = 5` | `db.users.find({id: 5})` |
| `SELECT * FROM users WHERE age > 18` | `db.users.find({age: {$gt: 18}})` |
| `SELECT * FROM users WHERE name LIKE '%Иван%'` | `db.users.find({name: {$regex: 'Иван'}})` |
| `SELECT * FROM users WHERE status IN ('a', 'b')` | `db.users.find({status: {$in: ['a', 'b']}})` |
| `INSERT INTO users (name) VALUES ('Иван')` | `db.users.insertOne({name: 'Иван'})` |
| `UPDATE users SET name = 'Пётр' WHERE id = 5` | `db.users.updateMany({id: 5}, {$set: {name: 'Пётр'}})` |
| `DELETE FROM users WHERE id = 5` | `db.users.deleteMany({id: 5})` |
## Архитектура
- **`src/main.py`**: Точка входа MCP сервера, обработка MCP протокола
- **`src/db_connector.py`**: Управление подключениями и делегирование адаптерам
- **`src/query_parser.py`**: Парсер запросов на естественном языке
- **`src/adapters/`**: Адаптеры баз данных
- **`sql_adapter.py`**: SQLite, MySQL, PostgreSQL
- **`mongo_adapter.py`**: MongoDB
## Запуск
### Прямой запуск
```bash
python -X utf8 -m src.main
```
### Через MCP клиент
После настройки MCP клиента сервер автоматически обрабатывает запросы.
---
# SQL MCP Server (English)
MCP (Model Context Protocol) server for executing database queries using natural language. Supports SQLite, MySQL, PostgreSQL, and MongoDB.
## Features
- **Natural Language Queries**: Write database queries in plain English or Russian
- **Multiple Database Support**: SQLite, MySQL, PostgreSQL, MongoDB
- **MCP Protocol**: Stdio communication with LLM clients
- **LLM Integration**: Includes prompts to help LLM use the server
- **SQL Operations**: SELECT, INSERT, UPDATE, DELETE, ALTER, CREATE DATABASE
- **Bulk Operations**: Multiple INSERT, UPDATE, DELETE in a single query
- **Schema Inspection**: List tables and table structure
- **Data Protection**: UPDATE, DELETE, DROP, and ALTER require explicit user confirmation
- **Batch Operations**: Single confirmation for multiple modifying operations
## Installation
1. **Clone the repository:**
```bash
git clone https://github.com/Processori7/SQL-MCP.git
cd SQL-MCP
```
2. **Create and activate a virtual environment (recommended):**
```bash
# Windows
python -m venv venv
venv\Scripts\activate
# Linux/macOS
python3 -m venv venv
source venv/bin/activate
```
3. **Install dependencies:**
```bash
pip install -r requirements.txt
```
## MCP Integration
### MCP Client Configuration
Add to your MCP client configuration (e.g., `cline_mcp_settings.json`):
```json
{
"mcpServers": {
"sql-stdio": {
"disabled": false,
"timeout": 60,
"type": "stdio",
"command": "python",
"args": ["-X", "utf8", "-m", "src.main"],
"env": {
"PYTHONPATH": "C:\\path\\to\\SQL-MCP",
"PYTHONIOENCODING": "utf-8"
}
}
}
}
```
**Note:** Replace `C:\\path\\to\\SQL-MCP` with the actual path to the project folder.
**Important for Windows:** The `-X utf8` flag and `PYTHONIOENCODING` variable ensure proper handling of non-ASCII characters.
## Available Tools
### 1. execute_query
Executes database queries using natural language or SQL.
**Parameters:**
- `db_type` (required): Database type - `'sqlite'`, `'mysql'`, `'postgresql'`, or `'mongodb'`
- `query` (required): Natural language query OR SQL/MongoDB query
- `db_config` or `config_file` (one is required): Database connection settings
- `confirm_changes` (optional): Confirmation for data modification/deletion operations
### 2. list_tables
Gets a list of all tables or collections in the database.
**Parameters:**
- `db_type` (required): Database type
- `db_config` or `config_file` (one is required): Database connection settings
### 3. get_table_schema
Gets the table schema (columns, types, constraints).
**Parameters:**
- `db_type` (required): Database type (not supported for MongoDB)
- `table_name` (required): Table name
- `db_config` or `config_file` (one is required): Database connection settings
## Usage Examples
### Connection Configuration
There are two ways to specify connection parameters:
#### Method 1: db_config parameter (JSON object)
##### MySQL
```json
{
"host": "localhost",
"port": 3306,
"user": "root",
"password": "mypassword",
"database": "mydb"
}
```
##### PostgreSQL
```json
{
"host": "localhost",
"port": 5432,
"user": "postgres",
"password": "mypassword",
"dbname": "mydb"
}
```
##### SQLite
```json
{
"db_name": "mydata.db"
}
```
##### MongoDB
```json
{
"uri": "mongodb://localhost:27017",
"database_name": "mydb"
}
```
#### Method 2: config_file parameter (path to file)
Specify the path to a configuration file. JSON and TXT formats are supported.
**JSON file example (mysql_config.json):**
```json
{
"host": "localhost",
"port": 3306,
"user": "root",
"password": "mypassword",
"database": "mydb"
}
```
**TXT file example (mysql_config.txt):**
```ini
# MySQL Configuration
host=localhost
port=3306
user=root
password=mypassword
database=mydb
```
**Using config_file:**
```json
{
"db_type": "mysql",
"query": "SELECT * FROM users",
"config_file": "C:/configs/mysql_config.json"
}
```
### Query Examples
#### Create Database (MySQL/PostgreSQL)
```json
{
"db_type": "mysql",
"query": "CREATE DATABASE my_new_db",
"db_config": {"host": "localhost", "port": 3306, "user": "root", "password": ""}
}
```
#### Create Table
```json
{
"db_type": "mysql",
"query": "CREATE TABLE users (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(100), email VARCHAR(100), age INT)",
"db_config": {"host": "localhost", "port": 3306, "user": "root", "password": "", "database": "my_new_db"}
}
```
#### Bulk INSERT
```json
{
"db_type": "mysql",
"query": "INSERT INTO users (name, email, age) VALUES ('John', 'john@mail.com', 25), ('Mary', 'mary@mail.com', 30)",
"db_config": {"host": "localhost", "port": 3306, "user": "root", "password": "", "database": "my_new_db"}
}
```
#### SELECT with Conditions
```json
{
"db_type": "mysql",
"query": "SELECT * FROM users WHERE age > 25",
"db_config": {"host": "localhost", "port": 3306, "user": "root", "password": "", "database": "my_new_db"}
}
```
#### Bulk UPDATE
```json
{
"db_type": "mysql",
"query": "UPDATE users SET status='active' WHERE id IN (1, 2, 3)",
"db_config": {"host": "localhost", "port": 3306, "user": "root", "password": "", "database": "my_new_db"},
"confirm_changes": true
}
```
#### Bulk DELETE
```json
{
"db_type": "mysql",
"query": "DELETE FROM users WHERE status='inactive'",
"db_config": {"host": "localhost", "port": 3306, "user": "root", "password": "", "database": "my_new_db"},
"confirm_changes": true
}
```
### MongoDB Examples
#### Find Documents
```json
{
"db_type": "mongodb",
"query": "db.users.find({age: {$gt: 25}})",
"db_config": {"uri": "mongodb://localhost:27017", "database_name": "mydb"}
}
```
#### Bulk INSERT (insertMany)
```json
{
"db_type": "mongodb",
"query": "db.users.insertMany([{name: 'John', age: 25}, {name: 'Mary', age: 30}])",
"db_config": {"uri": "mongodb://localhost:27017", "database_name": "mydb"}
}
```
#### Bulk UPDATE (updateMany)
```json
{
"db_type": "mongodb",
"query": "db.users.updateMany({status: 'pending'}, {$set: {status: 'active'}})",
"db_config": {"uri": "mongodb://localhost:27017", "database_name": "mydb"},
"confirm_changes": true
}
```
## Data Protection
Data-modifying operations are **blocked by default** and require explicit confirmation:
- `UPDATE` - data modification
- `DELETE` - data deletion
- `DROP` - table/collection deletion
- `ALTER` - structure modification
To execute these operations, the LLM must:
1. Receive a `"status": "blocked"` response
2. Ask the user for confirmation
3. After confirmation, retry the query with `confirm_changes: true`
## SQL to MongoDB Conversion
The server automatically converts SQL queries to MongoDB operations:
| SQL Query | MongoDB Equivalent |
|-----------|-------------------|
| `SELECT * FROM users` | `db.users.find({})` |
| `SELECT * FROM users WHERE id = 5` | `db.users.find({id: 5})` |
| `SELECT * FROM users WHERE age > 18` | `db.users.find({age: {$gt: 18}})` |
| `SELECT * FROM users WHERE name LIKE '%John%'` | `db.users.find({name: {$regex: 'John'}})` |
| `SELECT * FROM users WHERE status IN ('a', 'b')` | `db.users.find({status: {$in: ['a', 'b']}})` |
| `INSERT INTO users (name) VALUES ('John')` | `db.users.insertOne({name: 'John'})` |
| `UPDATE users SET name = 'Peter' WHERE id = 5` | `db.users.updateMany({id: 5}, {$set: {name: 'Peter'}})` |
| `DELETE FROM users WHERE id = 5` | `db.users.deleteMany({id: 5})` |
## Architecture
- **`src/main.py`**: MCP server entry point, MCP protocol handling
- **`src/db_connector.py`**: Connection management and adapter delegation
- **`src/query_parser.py`**: Natural language query parser
- **`src/adapters/`**: Database adapters
- **`sql_adapter.py`**: SQLite, MySQL, PostgreSQL
- **`mongo_adapter.py`**: MongoDB
## Running
### Direct Run
```bash
python -X utf8 -m src.main
```
### Via MCP Client
After configuring the MCP client, the server automatically handles requests.
