MCP MSSQL Сервер

Это сервер Model Context Protocol (MCP) для взаимодействия с SQL Server. Он позволяет моделям больших языков (LLM) выполнять запросы SQL, запускать хранимые процедуры и исследовать схемы баз данных с повышенной безопасностью и надежностью.

Функции

• Безопасное выполнение SQL-запросов : выполнение запросов SELECT в базах данных SQL Server. Все запросы анализируются и проверяются, чтобы гарантировать выполнение только операторов SELECT .

• Поддержка хранимых процедур : выполнение хранимых процедур с параметризованными входными данными.

• Исследование схемы : просмотр определений таблиц и столбцов базы данных с кэшированием результатов для повышения производительности.

• Надежное управление соединениями : использует глобальный пул соединений для эффективного повторного использования соединений с базой данных с настраиваемой логикой повторных попыток и тайм-аутами.

• Повышенная безопасность :

  • Анализ SQL-запросов и белый список только SELECT .

  • Переменная среды SQL_ALLOWED_DATABASES для внесения в белый список доступных баз данных.

  • Защита от распространенных шаблонов SQL-инъекций для переключения контекста базы данных.

  • Блокирует выполнение потенциально вредоносных системных процедур или команд в прямых запросах.

• Настраиваемое кэширование : информация о схеме базы данных кэшируется с настраиваемым временем жизни (TTL).

• Структурированное ведение журнала : интегрированный регистратор pino для подробных и структурированных журналов приложений.

• Готовность к Docker : простое развертывание с помощью Docker.

Быстрый старт

Использование Docker (рекомендуется)

Полные инструкции по настройке Docker см. в файле README Docker .

Конфигурация

Сервер настроен с использованием переменных окружения. Создайте файл .env в корневом каталоге (можно скопировать .env.example ), чтобы задать эти значения.

Подробное руководство по всем параметрам конфигурации и их настройке см. в разделе CONFIG .

Использование с Клодом

Чтобы добавить этот MCP-сервер в Claude CLI:

В разговоре с Клодом вы можете:

1. Выполнить запросы SELECT :

   <mcp:execute_query database="YourDatabaseName"> SELECT TOP 10 * FROM YourTable </mcp:execute_query>

   (Атрибут database является необязательным, если используется SQL_DATABASE по умолчанию или если SQL_ALLOWED_DATABASES подразумевает единственный выбор.)

2. Выполнение хранимых процедур:

   <mcp:execute_StoredProcedure database="YourDatabaseName"> { "procedure": "YourSchema.YourProcedureName", "parameters": [ {"name": "Param1", "type": "NVarChar", "value": "SomeValue"}, {"name": "Param2", "type": "Int", "value": 123} ] } </mcp:execute_StoredProcedure>

3. Изучите схему базы данных:

   <mcp:schema> YourDatabaseName </mcp:schema>

   (Если YourDatabaseName не указано, по умолчанию используется SQL_DATABASE , указанная в переменных среды.)

Обработка соединения

Этот сервер MCP использует глобальный, надежный пул соединений (встроенный пул библиотеки mssql ), управляемый DatabaseService .

• Эффективность : соединения используются повторно, что снижает накладные расходы на установление нового соединения для каждого запроса.

• Устойчивость : реализует логику повторных попыток с экспоненциальной задержкой для первоначального установления соединения.

• Нет состояния сеанса между вызовами : в отличие от модели сеанса на пользователя, этот сервер не гарантирует, что последующие вызовы MCP (например, два отдельных вызова execute_query ) из LLM будут использовать то же самое базовое соединение с базой данных. Поэтому специфичное для сеанса состояние, такое как временные таблицы или переменные сеанса, созданные в одном вызове, могут быть недоступны в другом. Каждый вызов следует считать атомарным с точки зрения состояния сеанса. Команда USE [database] выдается в каждой операции, если целевая база данных отличается от базы данных по умолчанию пула, обеспечивая контекст для этой конкретной операции.

Разработка

Настройка локального развития

Заметки о безопасности

• Только : сервер строго следит за тем, чтобы через инструмент execute_query можно было выполнять только запросы SELECT с использованием анализа SQL. Операторы DML (INSERT, UPDATE, DELETE) и DDL блокируются.

• Выполнение хранимых процедур : хотя хранимые процедуры могут выполнять любые действия, разрешенные их разрешениями, их выполнение управляется отдельно.

• Белый список баз данных : используйте переменную среды SQL_ALLOWED_DATABASES , чтобы ограничить, с какими базами данных сервер может взаимодействовать. Подробное объяснение этой функции и того, как она взаимодействует с SQL_DATABASE , см. DATABASE_WHITELISTING.md .

• Блокировка системных процедур : прямое выполнение общих системных процедур (например, sp_ , xp_ ) и команд типа RECONFIGURE или WAITFOR DELAY через execute_query блокируется. Для законных системных взаимодействий следует использовать хранимые процедуры.

• Проверка ввода : Имена баз данных для переключения контекста и имена хранимых процедур проходят проверку формата. Анализ SQL обеспечивает дополнительный уровень проверки для запросов.

• Параметризованные входные данные : параметры хранимых процедур обрабатываются библиотекой mssql , которая обычно параметризует их для предотвращения SQL-инъекций.

Поиск неисправностей

Если у вас возникли проблемы:

1. Проверьте логи контейнера: docker logs mssql-mcp (если используется Docker).

2. Проверьте вывод консоли сервера на наличие журналов pino, если он запущен локально.

3. Проверьте, что все необходимые переменные среды в файле .env установлены правильно, особенно SQL_PASSWORD , SQL_SERVER , SQL_USER и SQL_DATABASE .

4. Если вы установили эту переменную, убедитесь, что базы данных, к которым вы пытаетесь получить доступ, указаны в SQL_ALLOWED_DATABASES .

5. Подтвердите сетевое подключение к экземпляру SQL Server, на котором запущен сервер MCP.

6. Тестовые скрипты ( test-mcp.sh , test-session-persistence.sh ) могут нуждаться в проверке/обновлении.

Подробную информацию об устранении неполадок Docker см. в файле README Docker .