MCP-сервер для MySQL на базе NodeJS

Сервер Model Context Protocol, который обеспечивает доступ к базам данных MySQL. Этот сервер позволяет LLM проверять схемы баз данных и выполнять SQL-запросы.

Оглавление

• Требования

• Установка

  • Кузнечное дело

  • Клонировать в локальный репозиторий

• Компоненты

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

• Переменные среды

• Режим нескольких баз данных

• Разрешения, специфичные для схемы

• Тестирование

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

• Внося вклад

• Лицензия

Требования

• Node.js v18 или выше

• MySQL 5.7 или выше (рекомендуется MySQL 8.0+)

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

• Для операций записи: пользователь MySQL с привилегиями INSERT, UPDATE и/или DELETE.

Установка

Существует несколько способов установки и настройки сервера MCP, но наиболее распространенным является проверка этого сайта https://smithery.ai/server/@benborla29/mcp-server-mysql .

Курсор

Для Cursor IDE вы можете установить этот MCP-сервер с помощью следующей команды в своем проекте:

1. Посетите https://smithery.ai/server/@benborla29/mcp-server-mysql

2. Следуйте инструкциям для курсора.

MCP Get предоставляет централизованный реестр серверов MCP и упрощает процесс установки.

Использование NPM/PNPM

Для ручной установки:

После ручной установки вам необходимо настроить приложение LLM для использования сервера MCP (см. раздел «Конфигурация» ниже).

Запуск из локального репозитория

Если вы хотите клонировать и запустить этот сервер MCP непосредственно из исходного кода, выполните следующие действия:

1. Клонировать репозиторий

   git clone https://github.com/benborla/mcp-server-mysql.git cd mcp-server-mysql

2. Установить зависимости

   npm install # or pnpm install

3. Построить проект

   npm run build # or pnpm run build

4. Настроить рабочий стол Клода

   Добавьте следующее в файл конфигурации Claude Desktop ( claude_desktop_config.json ):

   { "mcpServers": { "mcp_server_mysql": { "command": "/path/to/node", "args": [ "/full/path/to/mcp-server-mysql/dist/index.js" ], "env": { "MYSQL_HOST": "127.0.0.1", "MYSQL_PORT": "3306", "MYSQL_USER": "root", "MYSQL_PASS": "your_password", "MYSQL_DB": "your_database", "ALLOW_INSERT_OPERATION": "false", "ALLOW_UPDATE_OPERATION": "false", "ALLOW_DELETE_OPERATION": "false", "PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/bin:/usr/bin:/bin", // <--- Important to add the following, run in your terminal `echo "$(which node)/../"` to get the path "NODE_PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/lib/node_modules" // <--- Important to add the following, run in your terminal `echo "$(which node)/../../lib/node_modules"` } } } }

   Заменять:

   • /path/to/node с полным путем к вашему двоичному файлу Node.js (найдите его с помощью which node )

   • /full/path/to/mcp-server-mysql с полным путем к месту, куда вы клонировали репозиторий

   • Установите учетные данные MySQL в соответствии с вашей средой.

5. Протестируйте сервер

   # Run the server directly to test node dist/index.js

   Если подключение к MySQL прошло успешно, вы готовы использовать его с Claude Desktop.

Компоненты

Инструменты

• mysql_query

  • Выполнение SQL-запросов к подключенной базе данных

  • Ввод: sql (строка): SQL-запрос для выполнения.

  • По умолчанию ограничено операциями ТОЛЬКО ЧТЕНИЕ

  • Дополнительные операции записи (если включены через конфигурацию):

    • INSERT: Добавить новые данные в таблицы (требуется ALLOW_INSERT_OPERATION=true )

    • ОБНОВЛЕНИЕ: изменение существующих данных (требуется ALLOW_UPDATE_OPERATION=true )

    • DELETE: Удалить данные (требуется ALLOW_DELETE_OPERATION=true )

  • Все операции выполняются в рамках транзакции с правильной обработкой фиксации/отката.

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

  • Настраиваемые тайм-ауты запросов и разбиение результатов на страницы

  • Встроенная статистика выполнения запросов

Ресурсы

Сервер предоставляет исчерпывающую информацию о базе данных:

• Схемы таблиц

  • Информация о схеме JSON для каждой таблицы

  • Имена столбцов и типы данных

  • Индексная информация и ограничения

  • Отношения внешнего ключа

  • Статистика и метрики таблиц

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

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

• Предотвращение SQL-инъекций с помощью подготовленных операторов

• Запрос возможностей белого/черного списка

• Ограничение скорости выполнения запроса

• Анализ сложности запроса

• Настраиваемое шифрование соединения

• Обеспечение транзакций только для чтения

Оптимизация производительности

• Оптимизированный пул соединений

• Кэширование результатов запроса

• Потоковая передача большого набора результатов

• Анализ плана выполнения запроса

• Настраиваемые тайм-ауты запросов

Мониторинг и отладка

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

• Сбор показателей производительности

• Отслеживание ошибок и сообщение о них

• Конечные точки проверки работоспособности

• Статистика выполнения запросов

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

Автоматическая конфигурация с кузницей

Если вы установили с помощью Smithery, ваша конфигурация уже настроена. Вы можете просмотреть или изменить ее с помощью:

При перенастройке вы можете обновить любые данные соединения MySQL, а также параметры операции записи:

• Основные настройки подключения :

  • MySQL Хост, Порт, Пользователь, Пароль, База данных

  • Конфигурация SSL/TLS (если ваша база данных требует защищенных соединений)

• Разрешения на запись операции :

  • Разрешить операции INSERT: установите значение true, если вы хотите разрешить добавление новых данных.

  • Разрешить операции UPDATE: установите значение true, если вы хотите разрешить обновление существующих данных.

  • Разрешить операции DELETE: установите значение true, если вы хотите разрешить удаление данных.

По соображениям безопасности все операции записи по умолчанию отключены. Включайте эти настройки только в том случае, если вам конкретно нужно, чтобы Клод изменил данные вашей базы данных.

Расширенные параметры конфигурации

Для большего контроля над поведением сервера MCP вы можете использовать следующие расширенные параметры конфигурации:

Переменные среды

Базовое подключение

• MYSQL_SOCKET_PATH : путь к сокету Unix для локальных подключений (например, "/tmp/mysql.sock")

• MYSQL_HOST : Хост сервера MySQL (по умолчанию: "127.0.0.1") — игнорируется, если задан MYSQL_SOCKET_PATH

• MYSQL_PORT : порт сервера MySQL (по умолчанию: «3306») — игнорируется, если задан MYSQL_SOCKET_PATH

• MYSQL_USER : имя пользователя MySQL (по умолчанию: «root»)

• MYSQL_PASS : пароль MySQL

• MYSQL_DB : Имя целевой базы данных (оставьте пустым для режима с несколькими базами данных)

Конфигурация производительности

• MYSQL_POOL_SIZE : Размер пула соединений (по умолчанию: «10»)

• MYSQL_QUERY_TIMEOUT : Время ожидани�� запроса в миллисекундах (по умолчанию: «30000»)

• MYSQL_CACHE_TTL : время жизни кэша в миллисекундах (по умолчанию: «60000»)

Конфигурация безопасности

• MYSQL_RATE_LIMIT : Максимальное количество запросов в минуту (по умолчанию: «100»)

• MYSQL_MAX_QUERY_COMPLEXITY : Максимальная оценка сложности запроса (по умолчанию: «1000»)

• MYSQL_SSL : включить шифрование SSL/TLS (по умолчанию: «false»)

• ALLOW_INSERT_OPERATION : включить операции INSERT (по умолчанию: «false»)

• ALLOW_UPDATE_OPERATION : включить операции UPDATE (по умолчанию: «false»)

• ALLOW_DELETE_OPERATION : Включить операции DELETE (по умолчанию: «false»)

• ALLOW_DDL_OPERATION : Включить операции DDL (по умолчанию: «false»)

• SCHEMA_INSERT_PERMISSIONS : разрешения INSERT, специфичные для схемы

• SCHEMA_UPDATE_PERMISSIONS : разрешения UPDATE, специфичные для схемы

• SCHEMA_DELETE_PERMISSIONS : разрешения DELETE, специфичные для схемы

• SCHEMA_DDL_PERMISSIONS : разрешения DDL, специфичные для схемы

• MULTI_DB_WRITE_MODE : включить операции записи в режиме нескольких баз данных (по умолчанию: «false»)

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

• MYSQL_ENABLE_LOGGING : включить ведение журнала запросов (по умолчанию: «false»)

• MYSQL_LOG_LEVEL : Уровень ведения журнала (по умолчанию: «info»)

• MYSQL_METRICS_ENABLED : включить метрики производительности (по умолчанию: «false»)

Режим нескольких баз данных

MCP-Server-MySQL поддерживает подключение к нескольким базам данных, когда не задана конкретная база данных. Это позволяет LLM запрашивать любую базу данных, к которой у пользователя MySQL есть доступ. Для получения полной информации см. README-MULTI-DB.md .

Включение режима нескольких баз данных

Чтобы включить режим multi-DB, просто оставьте переменную окружения MYSQL_DB пустой. В режиме multi-DB запросы требуют квалификации схемы:

Разрешения, специфичные для схемы

Для точного контроля над операциями базы данных MCP-Server-MySQL теперь поддерживает разрешения, специфичные для схемы. Это позволяет разным базам данных иметь разные уровни доступа (только чтение, чтение-запись и т. д.).

Пример конфигурации

Полную информацию и рекомендации по безопасности см. в файле README-MULTI-DB.md .

Тестирование

Настройка базы данных

Перед запуском тестов необходимо настроить тестовую базу данных и заполнить ее тестовыми данными:

1. Создать тестовую базу данных и пользователя

   -- Connect as root and create test database CREATE DATABASE IF NOT EXISTS mcp_test; -- Create test user with appropriate permissions CREATE USER IF NOT EXISTS 'mcp_test'@'localhost' IDENTIFIED BY 'mcp_test_password'; GRANT ALL PRIVILEGES ON mcp_test.* TO 'mcp_test'@'localhost'; FLUSH PRIVILEGES;

2. Запустить скрипт настройки базы данных

   # Run the database setup script pnpm run setup:test:db

   Это создаст необходимые таблицы и начальные данные. Скрипт находится в scripts/setup-test-db.ts

3. Настройте тестовую среду. Создайте файл .env.test в корне проекта (если он не существует):

   MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=mcp_test MYSQL_PASS=mcp_test_password MYSQL_DB=mcp_test

4. Обновление скриптов package.json Добавьте эти скрипты в ваш package.json:

   { "scripts": { "setup:test:db": "ts-node scripts/setup-test-db.ts", "pretest": "pnpm run setup:test:db", "test": "vitest run", "test:watch": "vitest", "test:coverage": "vitest run --coverage" } }

Проведение тестов

Проект включает в себя комплексный набор тестов для обеспечения функциональности и надежности:

Запуск оценок

Пакет evals загружает клиент mcp, который затем запускает файл index.ts, поэтому нет необходимости перестраиваться между тестами. Вы можете загрузить переменные среды, указав префикс команды npx. Полную документацию можно найти здесь .

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

Распространенные проблемы

1. Проблемы с подключением

   • Убедитесь, что сервер MySQL запущен и доступен.

   • Проверьте учетные данные и разрешения

   • Убедитесь, что конфигурация SSL/TLS корректна, если включена.

   • Попробуйте подключиться с помощью клиента MySQL для подтверждения доступа.

2. Проблемы с производительностью

   • Отрегулируйте размер пула соединений

   • Настройте значения времени ожидания запроса

   • При необходимости включите кэширование запросов.

   • Проверьте настройки сложности запроса

   • Мониторинг использования ресурсов сервера

3. Ограничения безопасности

   • Обзор конфигурации ограничения скорости

   • Проверьте настройки белого/черного списка запросов

   • Проверьте настройки SSL/TLS

   • Убедитесь, что у пользователя есть соответствующие разрешения MySQL.

4. Разрешение пути Если вы столкнулись с ошибкой «Не удалось подключиться к серверу MCP mcp-server-mysql», явно укажите путь ко всем необходимым двоичным файлам:

Где я могу найти путь к bin-файлу моего Чтобы получить его, выполните следующую команду:

Для ПУТИ

Для NODE_PATH

5. Конкретные проблемы Claude Desktop

   • Если вы видите журналы «Сервер отключен» в Claude Desktop, проверьте журналы в ~/Library/Logs/Claude/mcp-server-mcp_server_mysql.log

   • Убедитесь, что вы используете абсолютный путь как к двоичному файлу Node, так и к серверному скрипту.

   • Проверьте, правильно ли загружается ваш файл .env ; используйте явные переменные среды в конфигурации.

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

   • Если вам нужны операции записи (INSERT, UPDATE, DELETE), установите соответствующие флаги в значение «true» в вашей конфигурации:

     "env": { "ALLOW_INSERT_OPERATION": "true", // Enable INSERT operations "ALLOW_UPDATE_OPERATION": "true", // Enable UPDATE operations "ALLOW_DELETE_OPERATION": "true" // Enable DELETE operations }

   • Убедитесь, что у вашего пользователя MySQL есть соответствующие разрешения для операций, которые вы включаете.

   • Для конфигурации прямого выполнения используйте:

     { "mcpServers": { "mcp_server_mysql": { "command": "/full/path/to/node", "args": [ "/full/path/to/mcp-server-mysql/dist/index.js" ], "env": { "MYSQL_HOST": "127.0.0.1", "MYSQL_PORT": "3306", "MYSQL_USER": "root", "MYSQL_PASS": "your_password", "MYSQL_DB": "your_database" } } } }

6. Проблемы с аутентификацией

   • Для MySQL 8.0+ убедитесь, что сервер поддерживает плагин аутентификации caching_sha2_password

   • Проверьте, настроен ли для вашего пользователя MySQL правильный метод аутентификации.

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

     CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';

     @lizhuangs

7. Я столкнулся с Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from ошибки. Попробуйте это решение:

Спасибо @lizhuangs

Внося вклад

Вклады приветствуются! Пожалуйста, не стесняйтесь отправлять запрос на извлечение по адресу https://github.com/benborla/mcp-server-mysql

Большое спасибо следующим участникам:

Настройка разработки

1. Клонировать репозиторий

2. Установите зависимости: pnpm install

3. Соберите проект: pnpm run build

4. Запуск тестов: pnpm test

Дорожная карта проекта

Мы активно работаем над улучшением этого сервера MCP. Проверьте наш CHANGELOG.md для получения подробной информации о запланированных функциях, включая:

• Расширенные возможности запросов с подготовленными заявлениями

• Расширенные функции безопасности

• Оптимизация производительности

• Комплексный мониторинг

• Расширенная информация о схеме

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

Отправка изменений

1. Форк репозитория

2. Создайте ветку функции: git checkout -b feature/your-feature-name

3. Зафиксируйте изменения: git commit -am 'Add some feature'

4. Отправка в ветку: git push origin feature/your-feature-name

5. Отправить запрос на извлечение

Лицензия

Этот сервер MCP лицензирован по лицензии MIT. Подробности см. в файле LICENSE.