MS SQL MCP-сервер 1.1

Простой в использовании мост, который позволяет помощникам ИИ, таким как Клод, напрямую запрашивать и исследовать базы данных Microsoft SQL Server. Опыт кодирования не требуется!

Что делает этот инструмент?

Этот инструмент позволяет помощникам на основе искусственного интеллекта:

1. Найдите таблицы в вашей базе данных SQL Server

2. Просмотр структур таблиц (столбцов, типов данных и т. д.)

3. Безопасное выполнение SQL-запросов только для чтения

4. Генерация SQL-запросов из запросов на естественном языке

Related MCP server: MS SQL MCP Server

🌟 Зачем вам нужен этот инструмент

Преодолейте разрыв между вашими данными и ИИ

• Не требуется кодирования : предоставьте Клоду и другим помощникам на базе искусственного интеллекта прямой доступ к вашим базам данных SQL Server без написания сложного кода интеграции.

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

• Конфиденциально и безопасно : ваши учетные данные базы данных остаются локальными и никогда не отправляются на внешние службы.

Практические преимущества

• Экономьте часы ручной работы : больше не нужно копировать и вставлять данные или результаты запросов для передачи ИИ

• Более глубокий анализ : ИИ может перемещаться по всей схеме базы данных и предоставлять информацию по нескольким таблицам.

• Интерфейс на естественном языке : задавайте вопросы о своих данных на простом английском языке.

• Устранение проблемы ограничения контекста : доступ к большим наборам данных, которые превышают обычные окна контекста ИИ.

Идеально подходит для

• Аналитики данных , которым нужна помощь ИИ в интерпретации данных SQL без предоставления учетных данных

• Разработчики, ищущие быстрый способ исследования структуры базы данных посредством естественного общения

• Бизнес-аналитики , которым нужна информация без знаний SQL

• Администраторы баз данных , желающие обеспечить контролируемый доступ к инструментам ИИ

🚀 Краткое руководство пользователя

Шаг 1: Установка необходимых компонентов

• Установите Node.js (версии 14 или выше)

• Иметь доступ к базе данных Microsoft SQL Server (локальной или Azure)

Шаг 2: Клонирование и настройка

# Clone this repository
git clone https://github.com/dperussina/mssql-mcp-server.git

# Navigate to the project directory
cd mssql-mcp-server

# Install dependencies
npm install

# Copy the example environment file
cp .env.example .env

Шаг 3: Настройте подключение к базе данных

Отредактируйте файл .env , используя учетные данные вашей базы данных:

DB_USER=your_username
DB_PASSWORD=your_password
DB_SERVER=your_server_name_or_ip
DB_DATABASE=your_database_name
PORT=3333
HOST=0.0.0.0                    # Host for the server to listen on, e.g., 'localhost' or '0.0.0.0'
TRANSPORT=stdio
SERVER_URL=http://localhost:3333
DEBUG=false                     # Set to 'true' for detailed logging (helpful for troubleshooting)
QUERY_RESULTS_PATH=/path/to/query_results  # Directory where query results will be saved as JSON files

Шаг 4: Запустите сервер

# Start with default stdio transport
npm start

# OR start with HTTP/SSE transport for network access
npm run start:sse

Шаг 5: Попробуйте!

# Run the interactive client
npm run client

📊 Примеры использования

1. Исследуйте структуру вашей базы данных без написания SQL

   mcp_SQL_mcp_discover_database()

2. Получить подробную информацию о конкретной таблице

   mcp_SQL_mcp_table_details({ tableName: "Customers" })

3. Выполнить безопасный запрос

   mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Customers", returnResults: true })

4. Найти таблицы по шаблону имени

   mcp_SQL_mcp_discover_tables({ namePattern: "%user%" })

5. Используйте пагинацию для навигации по большим наборам результатов

   // First page
   mcp_SQL_mcp_execute_query({ 
     sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY", 
     returnResults: true 
   })
   
   // Next page
   mcp_SQL_mcp_execute_query({ 
     sql: "SELECT * FROM Users ORDER BY Username OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY", 
     returnResults: true 
   })

6. Разбиение на страницы с помощью курсора для оптимальной производительности

   // First page
   mcp_SQL_mcp_execute_query({ 
     sql: "SELECT TOP 10 * FROM Users ORDER BY Username", 
     returnResults: true 
   })
   
   // Next page using the last value as cursor
   mcp_SQL_mcp_execute_query({ 
     sql: "SELECT TOP 10 * FROM Users WHERE Username > 'last_username' ORDER BY Username", 
     returnResults: true 
   })

7. Задавайте вопросы на естественном языке

   "Show me the top 5 customers with the most orders in the last month"

💡 Реальные приложения

Для бизнес-аналитики

• Анализ эффективности продаж : «Покажите мне ежемесячные тенденции продаж за последний год и определите наши самые эффективные продукты по регионам».

• Сегментация клиентов : «Проанализируйте нашу клиентскую базу по частоте покупок, средней стоимости заказа и географическому положению».

• Финансовая отчетность : «Создайте квартальный отчет о прибылях и убытках, сравнив этот год с прошлым годом».

Для управления базами данных

• Оптимизация схемы : «Помогите мне определить таблицы с отсутствующими индексами, изучив данные о производительности запросов».

• Аудит качества данных : «Найдите все записи о клиентах с неполной информацией или недействительными значениями».

• Анализ использования : «Покажите мне, к каким таблицам чаще всего обращаются и какие запросы являются наиболее ресурсоемкими».

Для развития

• Исследование API : «Я создаю API — помогите мне проанализировать схему базы данных для проектирования соответствующих конечных точек».

• Оптимизация запроса : «Просмотрите этот сложный запрос и предложите улучшения производительности».

• Документация базы данных : «Создание полной документации структуры нашей базы данных с пояснениями взаимосвязей».

🖥️ Интерактивные функции клиента

Встроенный клиент предоставляет простой интерфейс на основе меню:

1. Перечислите доступные ресурсы . Посмотрите, какая информация доступна.

2. Список доступных инструментов . Посмотрите, какие действия вы можете выполнить.

3. Выполнить SQL-запрос — выполнить SQL-запрос только для чтения

4. Получить сведения о таблице - Просмотреть структуру любой таблицы

5. Прочитать схему базы данных - Просмотреть все таблицы и их связи

6. Генерация SQL-запроса — преобразование естественного языка в SQL

🧠 Эффективное руководство по подсказкам и использованию инструментов

При работе с Клодом или другими помощниками ИИ через этот сервер MCP, то, как вы формулируете свои запросы, существенно влияет на результаты. Вот как помочь ИИ эффективно использовать инструменты базы данных:

Базовый формат вызова инструмента

При запросе ИИ использовать этот инструмент следуйте следующей структуре:

Can you use the SQL MCP tools to [your goal]?

For example:
- Check what tables exist in my database
- Query the Customers table and show me the first 10 records
- Find all orders from the past month

Основные команды и синтаксис

Вот основные инструменты и их правильный синтаксис:

// Discover the database structure
mcp_SQL_mcp_discover_database()

// Get detailed information about a specific table
mcp_SQL_mcp_table_details({ tableName: "YourTableName" })

// Execute a query and return results
mcp_SQL_mcp_execute_query({ 
  sql: "SELECT * FROM YourTable WHERE Condition", 
  returnResults: true 
})

// Find tables by name pattern
mcp_SQL_mcp_discover_tables({ namePattern: "%pattern%" })

// Access saved query results (for large result sets)
mcp_SQL_mcp_get_query_results({ uuid: "provided-uuid-here" })

Когда использовать каждый инструмент:

• Обнаружение базы данных : начните с этого, когда ИИ не знаком со структурой вашей базы данных.

• Сведения о таблице : используйте при необходимости сосредоточиться на определенной таблице перед написанием запросов.

• Выполнение запроса : когда вам необходимо извлечь или проанализировать фактические данные.

• Обнаружение таблиц по шаблону : при поиске таблиц, относящихся к определенному домену.

Эффективные модели подсказок

Пошаговые рабочие процессы

Для сложных задач проведите ИИ через ряд шагов:

I'd like to analyze our sales data. Please:
1. First use mcp_SQL_mcp_discover_tables to find tables related to sales
2. Use mcp_SQL_mcp_table_details to examine the structure of relevant tables
3. Create a query with mcp_SQL_mcp_execute_query that shows monthly sales by product category

Сначала структура, потом запрос

First, discover what tables exist in my database. Then, look at the structure
of the Customers table. Finally, show me the top 10 customers by total purchase amount.

Попросите объяснений

Query the top 5 underperforming products based on sales vs. forecasts,
and explain your approach to writing this query.

Заметки о диалекте SQL Server

Напомните ИИ об особом синтаксисе SQL Server:

Please use SQL Server syntax for pagination:
- For offset/fetch: "OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY"
- For cursor-based: "WHERE ID > last_id ORDER BY ID"

Исправление использования инструмента

Если ИИ использует неправильный синтаксис, вы можете помочь ему:

That's not quite right. Please use this format for the tool call:
mcp_SQL_mcp_execute_query({ 
  sql: "SELECT * FROM Customers WHERE Region = 'West'",
  returnResults: true
})

Устранение неполадок с помощью подсказок

Если ИИ испытывает трудности с задачей базы данных, попробуйте следующие подходы:

1. Будьте более конкретны в отношении таблиц: «Прежде чем писать этот запрос, проверьте, существует ли таблица CustomerOrders и какие столбцы в ней есть».

2. Разбейте сложные задачи на этапы: «Давайте подойдем к этому шаг за шагом. Сначала посмотрите на структуру таблицы «Продукты». Затем проверьте таблицу «Заказы»...»

3. Запросите промежуточные результаты: «Сначала выполните простой запрос к этой таблице, чтобы мы могли проверить формат данных, прежде чем пытаться выполнить более сложный анализ».

4. Запрос пояснений к запросу: «После написания этого запроса объясните, что делает каждая его часть, чтобы я мог убедиться, что она делает то, что мне нужно».

🔎 Расширенные возможности запросов

Таблица открытий и исследований

Сервер MCP предоставляет мощные инструменты для исследования структуры вашей базы данных:

• Обнаружение таблиц на основе шаблонов : поиск таблиц, соответствующих определенным шаблонам.

  mcp_SQL_mcp_discover_tables({ namePattern: "%order%" })

• Обзор схемы : получите общее представление таблиц по схеме.

  mcp_SQL_mcp_execute_query({ 
    sql: "SELECT TABLE_SCHEMA, COUNT(*) AS TableCount FROM INFORMATION_SCHEMA.TABLES GROUP BY TABLE_SCHEMA" 
  })

• Исследование столбцов : изучение метаданных столбцов для любой таблицы.

  mcp_SQL_mcp_table_details({ tableName: "dbo.Users" })

Методы пагинации

Сервер поддерживает несколько методов пагинации для обработки больших наборов данных:

1. Разбиение на страницы с помощью Offset/Fetch : стандартная пагинация SQL с использованием OFFSET и FETCH

   mcp_SQL_mcp_execute_query({ 
     sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY" 
   })

2. Разбиение на страницы на основе курсора : более эффективно для больших наборов данных

   // Get first page
   mcp_SQL_mcp_execute_query({ 
     sql: "SELECT TOP 10 * FROM Users ORDER BY Username" 
   })
   
   // Get next page using last value as cursor
   mcp_SQL_mcp_execute_query({ 
     sql: "SELECT TOP 10 * FROM Users WHERE Username > 'last_username' ORDER BY Username" 
   })

3. Подсчет с данными : получение общего количества вместе с постраничными данными

   mcp_SQL_mcp_execute_query({ 
     sql: "WITH TotalCount AS (SELECT COUNT(*) AS Total FROM Users) SELECT TOP 10 u.*, t.Total FROM Users u CROSS JOIN TotalCount t ORDER BY Username" 
   })

Сложные соединения и отношения

Изучите связи между таблицами с помощью операций соединения:

mcp_SQL_mcp_execute_query({ 
  sql: "SELECT u.Username, u.Email, r.RoleName FROM Users u JOIN UserRoles ur ON u.Username = ur.Username JOIN Roles r ON ur.RoleId = r.RoleId ORDER BY u.Username"
})

Аналитические запросы

Выполняйте агрегации и аналитические запросы для получения информации:

mcp_SQL_mcp_execute_query({ 
  sql: "SELECT UserType, COUNT(*) AS UserCount, SUM(CASE WHEN IsActive = 1 THEN 1 ELSE 0 END) AS ActiveUsers FROM Users GROUP BY UserType"
})

Использование функций SQL Server

Сервер MCP поддерживает специфические функции SQL Server:

• Общие табличные выражения (CTE)

• Оконные функции

• Операции JSON

• Иерархические запросы

• Полнотекстовый поиск (если настроен в вашей базе данных)

🔗 Варианты интеграции

Интеграция рабочего стола Клода

Подключите этот инструмент напрямую к Claude Desktop, выполнив несколько простых шагов:

1. Установите Claude Desktop с anthropic.com

2. Отредактируйте файл конфигурации Клода:

   • Расположение: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Добавьте эту конфигурацию:

{
    "mcpServers": {
        "mssql": {
            "command": "node",
            "args": [
                "/FULL/PATH/TO/mssql-mcp-server/server.mjs"
            ]
        }
    }
}

3. Замените /FULL/PATH/TO/ на фактический путь к месту, куда вы клонировали этот репозиторий.

4. Перезагрузить рабочий стол Клода

5. Найдите значок инструментов в Claude Desktop — теперь вы можете использовать команды базы данных напрямую!

Подключение к Cursor IDE

Cursor — это редактор кода на базе искусственного интеллекта, который может использовать этот инструмент для расширенного взаимодействия с базой данных. Вот как его настроить:

Настройка в курсоре

1. Откройте Cursor IDE (загрузите с cursor.sh , если у вас его нет)

2. Запустите сервер MS SQL MCP с использованием транспорта HTTP/SSE:

   npm run start:sse

3. Создайте новое рабочее пространство или откройте существующий проект в курсоре

4. Введите настройки курсора

5. Нажмите МКП

6. Добавить новый сервер MCP

7. Назовите свой сервер MCP, выберите тип: sse

8. Введите URL-адрес сервера как: localhost:3333/sse (или порт, на котором он запущен)

Использование команд базы данных в курсоре

После подключения вы сможете использовать команды MCP непосредственно в чате искусственного интеллекта Курсора:

1. Попросите Клода в Курсоре изучить вашу базу данных:

   Can you show me the tables in my database?

2. Выполнение определенных запросов:

   Query the top 10 records from the Customers table

3. Генерация и выполнение сложных запросов:

   Find all orders from the last month with a value over $1000

Устранение неполадок с подключением курсора

• Убедитесь, что сервер MS SQL MCP работает с транспортом HTTP/SSE.

• Проверьте правильность порта и его соответствие указанному в файле .env.

• Убедитесь, что ваш брандмауэр не блокирует соединение.

• Если вы используете другой IP/имя хоста, обновите SERVER_URL в вашем файле .env.

🔄 Объяснение методов транспортировки

Вариант 1: stdio Transport (по умолчанию)

Лучше всего подходит для: использования напрямую с Claude Desktop или встроенным клиентом

npm start

Вариант 2: HTTP/SSE-транспорт

Лучше всего подходит для: доступа к сети или использования с веб-приложениями.

npm run start:sse

🛡️ Функции безопасности

• По умолчанию доступно только чтение : нет риска изменения данных.

• Личные учетные данные : сведения о подключении к базе данных сохраняются в вашем файле .env

• Защита от SQL-инъекций : встроенная проверка SQL-запросов

🔎 Устранение неполадок для новых пользователей

«Невозможно подключиться к базе данных»

• Проверьте правильность учетных данных базы данных в файле .env

• Убедитесь, что ваш SQL Server работает и принимает соединения.

• Для Azure SQL убедитесь, что ваш IP-адрес разрешен в настройках брандмауэра.

Ошибки «Модуль не найден»

• Запустите npm install еще раз, чтобы убедиться, что все зависимости установлены.

• Убедитесь, что вы используете Node.js версии 14 или выше.

«Ошибка транспорта» или «Отказано в соединении»

• Для транспорта HTTP/SSE проверьте, доступен ли PORT в вашем .env.

• Убедитесь, что брандмауэр не блокирует соединение.

Claude Desktop не может подключиться

• Дважды проверьте путь в вашем claude_desktop_config.json

• Убедитесь, что вы используете абсолютные пути, а не относительные.

• Полностью перезагрузите Claude Desktop после внесения изменений.

📚 Понимание основ SQL Server

Если вы новичок в SQL Server, вот несколько ключевых понятий:

• Таблицы : храните данные в строках и столбцах.

• Схемы : Логические группировки таблиц (например, папки)

• Запросы : команды для извлечения или анализа данных.

• Просмотры : Предопределенные запросы, сохраненные для легкого доступа

Этот инструмент поможет вам изучить все это, даже если вам не нужно быть экспертом по SQL!

🏗️ Архитектура и основные модули

Сервер MS SQL MCP построен на основе модульной архитектуры, которая разделяет вопросы удобства обслуживания и расширяемости:

Основные модули

database.mjs — подключение к базе данных

• Управляет пулом соединений SQL Server

• Обеспечивает выполнение запросов с логикой повторных попыток и обработкой ошибок.

• Управляет подключениями к базе данных, транзакциями и конфигурацией

• Включает утилиты для очистки SQL и ошибок форматирования.

tools.mjs — Регистрация инструмента

• Регистрирует все инструменты базы данных на сервере MCP

• Реализует проверку инструментов и параметров

• Предоставляет основные функции для SQL-запросов, исследования таблиц и обнаружения баз данных.

• Сопоставляет вызовы инструментов с операциями базы данных

resources.mjs — Ресурсы базы данных

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

• Предоставляет информацию о схеме, списки таблиц и документацию по процедурам.

• Форматирует информацию о структуре базы данных для использования ИИ

• Включает в себя утилиты обнаружения для исследования базы данных

pagination.mjs - Результаты навигации

• Реализует разбиение на страницы с помощью курсора для больших наборов результатов

• Предоставляет утилиты для создания курсоров следующей/предыдущей страницы.

• Преобразует SQL-запросы для поддержки пагинации

• Обрабатывает синтаксис пагинации OFFSET/FETCH SQL Server

errors.mjs - Обработка ошибок

• Определяет пользовательские типы ошибок для различных сценариев сбоев.

• Реализует форматирование ошибок JSON-RPC

• Предоставляет понятные человеку сообщения об ошибках

• Включает промежуточное программное обеспечение для глобальной обработки ошибок.

logger.mjs - Система ведения журнала

• Настраивает ведение журнала Winston с несколькими транспортами

• Обеспечивает контекстно-зависимую регистрацию запросов

• Управляет ротацией и форматированием журналов

• Захватывает неперехваченные исключения и необработанные отклонения

Как эти модули работают вместе

1. При получении вызова инструмента сервер MCP направляет его соответствующему обработчику в tools.mjs

2. Обработчик инструмента проверяет параметры и создает запрос к базе данных.

3. Запрос выполняется с помощью функций в database.mjs , с возможной пагинацией из pagination.mjs

4. Результаты форматируются и возвращаются клиенту.

5. Любые ошибки отлавливаются и обрабатываются через errors.mjs

6. Все операции регистрируются через logger.mjs

Такая архитектура обеспечивает:

• Четкое разделение интересов

• Последовательная обработка ошибок

• Комплексное ведение журнала

• Эффективное управление подключением к базе данных

• Масштабируемое выполнение запросов

⚙️ Объяснение конфигурации среды

Файл .env управляет тем, как MS SQL MCP Server подключается к вашей базе данных и работает. Вот подробное объяснение каждой настройки:

# Database Connection Settings
DB_USER=your_username           # SQL Server username
DB_PASSWORD=your_password       # SQL Server password
DB_SERVER=your_server_name_or_ip
DB_DATABASE=your_database_name

# Server Configuration
PORT=3333                       # Port for the HTTP/SSE server to listen on
HOST=0.0.0.0                    # Host for the server to listen on, e.g., 'localhost' or '0.0.0.0'
TRANSPORT=stdio                 # Connection method: 'stdio' (for Claude Desktop) or 'sse' (for network connections)
SERVER_URL=http://localhost:3333 # Base URL when using SSE transport. If HOST is '0.0.0.0', external clients use http://<your-machine-ip>:${PORT}

# Advanced Settings
DEBUG=false                     # Set to 'true' for detailed logging (helpful for troubleshooting)
QUERY_RESULTS_PATH=/path/to/query_results  # Directory where query results will be saved as JSON files

Объяснение типов подключения

stdio транспорт

• Используйте при прямом подключении к Claude Desktop

• Связь осуществляется через стандартные потоки ввода/вывода.

• Установите TRANSPORT=stdio в вашем .env-файле

• Запустить с помощью npm start

HTTP/SSE-транспорт

• Использовать при подключении по сети (например, с Cursor IDE)

• Использует отправленные сервером события (SSE) для связи в реальном времени

• Установите TRANSPORT=sse в вашем .env-файле

• Настройте SERVER_URL так, чтобы он соответствовал адресу вашего сервера

• Запустить с помощью npm run start:sse

Примеры подключения к SQL Server

Локальный SQL-сервер

DB_USER=sa
DB_PASSWORD=YourStrongPassword
DB_SERVER=localhost
DB_DATABASE=AdventureWorks

База данных Azure SQL

DB_USER=azure_admin@myserver
DB_PASSWORD=YourStrongPassword
DB_SERVER=myserver.database.windows.net
DB_DATABASE=AdventureWorks

Хранилище результатов запросов

Результаты запроса сохраняются в виде файлов JSON в каталоге, указанном QUERY_RESULTS_PATH . Это предотвращает перегрузку беседы большими наборами результатов. Вы можете:

• Оставьте это поле пустым, чтобы использовать каталог query-results по умолчанию в проекте.

• Задайте пользовательский путь, например /Users/username/Documents/query-results

• Доступ к сохраненным результатам с помощью предоставленного UUID в ответе инструмента

📝 Лицензия

МСК