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. Клонируйте репозиторий:

   git clone https://github.com/Processori7/SQL-MCP.git
   cd SQL-MCP
   

2. Создайте и активируйте виртуальное окружение (рекомендуется):

   # Windows
   python -m venv venv
   venv\Scripts\activate
   
   # Linux/macOS
   python3 -m venv venv
   source venv/bin/activate
   

3. Установите зависимости:

   pip install -r requirements.txt
   

Интеграция с MCP

Настройка MCP клиента

Добавьте в конфигурацию вашего MCP клиента (например, cline_mcp_settings.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

{
  "host": "localhost",
  "port": 3306,
  "user": "root",
  "password": "mypassword",
  "database": "mydb"
}

PostgreSQL

{
  "host": "localhost",
  "port": 5432,
  "user": "postgres",
  "password": "mypassword",
  "dbname": "mydb"
}

SQLite

{
  "db_name": "mydata.db"
}

MongoDB

{
  "uri": "mongodb://localhost:27017",
  "database_name": "mydb"
}

Способ 2: Параметр config_file (путь к файлу)

Укажите путь к файлу конфигурации. Поддерживаются форматы JSON и TXT.

Пример JSON файла (mysql_config.json):

{
  "host": "localhost",
  "port": 3306,
  "user": "root",
  "password": "mypassword",
  "database": "mydb"
}

Пример TXT файла (mysql_config.txt):

# Конфигурация MySQL
host=localhost
port=3306
user=root
password=mypassword
database=mydb

Использование config_file:

{
  "db_type": "mysql",
  "query": "SELECT * FROM users",
  "config_file": "C:/configs/mysql_config.json"
}

Или с относительным путём:

{
  "db_type": "mysql",
  "query": "SHOW TABLES",
  "config_file": "mysql_config.txt"
}

Примеры запросов

Создание базы данных (MySQL/PostgreSQL)

{
  "db_type": "mysql",
  "query": "CREATE DATABASE my_new_db",
  "db_config": {"host": "localhost", "port": 3306, "user": "root", "password": ""}
}

Или на естественном языке:

{
  "db_type": "mysql",
  "query": "Создай БД my_new_db",
  "db_config": {"host": "localhost", "port": 3306, "user": "root", "password": ""}
}

Переключение базы данных

{
  "db_type": "mysql",
  "query": "USE my_new_db",
  "db_config": {"host": "localhost", "port": 3306, "user": "root", "password": "", "database": "my_new_db"}
}

Создание таблицы

{
  "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 (множественная вставка)

{
  "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 с условиями

{
  "db_type": "mysql",
  "query": "SELECT * FROM users WHERE age > 25",
  "db_config": {"host": "localhost", "port": 3306, "user": "root", "password": "", "database": "my_new_db"}
}

Или на естественном языке:

{
  "db_type": "mysql",
  "query": "Покажи всех пользователей где возраст больше 25",
  "db_config": {"host": "localhost", "port": 3306, "user": "root", "password": "", "database": "my_new_db"}
}

Bulk UPDATE (множественное обновление)

{
  "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 (множественное удаление)

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

Поиск документов

{
  "db_type": "mongodb",
  "query": "db.users.find({age: {$gt: 25}})",
  "db_config": {"uri": "mongodb://localhost:27017", "database_name": "mydb"}
}

Bulk INSERT (insertMany)

{
  "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)

{
  "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)

{
  "db_type": "mongodb",
  "query": "db.users.deleteMany({status: 'inactive'})",
  "db_config": {"uri": "mongodb://localhost:27017", "database_name": "mydb"},
  "confirm_changes": true
}

findOneAndUpdate

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

Запуск

Прямой запуск

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:

   git clone https://github.com/Processori7/SQL-MCP.git
   cd SQL-MCP
   

2. Create and activate a virtual environment (recommended):

   # Windows
   python -m venv venv
   venv\Scripts\activate
   
   # Linux/macOS
   python3 -m venv venv
   source venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

MCP Integration

MCP Client Configuration

Add to your MCP client configuration (e.g., cline_mcp_settings.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

{
  "host": "localhost",
  "port": 3306,
  "user": "root",
  "password": "mypassword",
  "database": "mydb"
}

PostgreSQL

{
  "host": "localhost",
  "port": 5432,
  "user": "postgres",
  "password": "mypassword",
  "dbname": "mydb"
}

SQLite

{
  "db_name": "mydata.db"
}

MongoDB

{
  "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):

{
  "host": "localhost",
  "port": 3306,
  "user": "root",
  "password": "mypassword",
  "database": "mydb"
}

TXT file example (mysql_config.txt):

# MySQL Configuration
host=localhost
port=3306
user=root
password=mypassword
database=mydb

Using config_file:

{
  "db_type": "mysql",
  "query": "SELECT * FROM users",
  "config_file": "C:/configs/mysql_config.json"
}

Query Examples

Create Database (MySQL/PostgreSQL)

{
  "db_type": "mysql",
  "query": "CREATE DATABASE my_new_db",
  "db_config": {"host": "localhost", "port": 3306, "user": "root", "password": ""}
}

Create Table

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

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

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

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

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

{
  "db_type": "mongodb",
  "query": "db.users.find({age: {$gt: 25}})",
  "db_config": {"uri": "mongodb://localhost:27017", "database_name": "mydb"}
}

Bulk INSERT (insertMany)

{
  "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)

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

python -X utf8 -m src.main

Via MCP Client

After configuring the MCP client, the server automatically handles requests.