mcp-mysql-client

MySQL MCP

MySQL MCP подключает AI-приложение к одной базе MySQL или MariaDB: посмотреть структуру, задать вопрос данным на естественном языке, разобраться в медленном запросе — и, если вы сами это разрешили, изменить данные.

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

• 6 инструментов. Подключение и права, список таблиц, структура таблицы, читающий запрос, план запроса, изменяющий запрос.
• Тип запроса определяет сервер. SQL разбирается до подключения: DELETE в читающем инструменте будет отклонён, даже если права на запись включены.
• Чтение не может писать. Читающие запросы идут внутри START TRANSACTION READ ONLY — запись отклонит сама MySQL, даже если разбор SQL кто-то обманет.
• Ответ не переполнит контекст. Строки читаются потоком и обрываются на лимите, а не выкачиваются целиком; в ответе честный признак truncated.
• Права только снаружи. INSERT, UPDATE и DELETE включаются переменными окружения и требуют перезапуска — из диалога их получить нельзя. DDL недоступен всегда.

Начните с запроса, который только читает данные:

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

---

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

Claude Code:

claude mcp add mysql-myapp \
  -e MYSQL_HOST=db.example.com \
  -e MYSQL_USER=myapp_ro \
  -e MYSQL_PASS='пароль' \
  -e MYSQL_DB=myapp \
  -e MYSQL_SSL=true \
  -- npx -y mcp-mysql-client

Или в .mcp.json / claude_desktop_config.json:

{
  "mcpServers": {
    "mysql-myapp": {
      "command": "npx",
      "args": ["-y", "mcp-mysql-client"],
      "env": {
        "MYSQL_HOST": "db.example.com",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "myapp_ro",
        "MYSQL_PASS": "пароль",
        "MYSQL_DB": "myapp",
        "MYSQL_SSL": "true"
      }
    }
  }
}

Один сервер — одна база. Нужно несколько баз: добавьте несколько записей со своими учётными данными; так права остаются изолированными, и сервер, подключённый к тестовой базе, физически не видит боевую.

Что можно поручить

Запрос	Что делает сервер
«Что вообще есть в этой базе?»	list_tables — таблицы, размеры, оценки числа строк
«Как устроена таблица orders?»	describe_table — столбцы, индексы, внешние ключи в обе стороны
«Сколько заказов за июль и на какую сумму?»	query — SELECT с агрегацией
«Почему этот запрос медленный?»	explain — план, индексы, оценка строк
«Под кем я подключён и что мне можно?»	server_info — база, пользователь, GRANT, лимиты сервера
«Проставь статус отменённым заказам»	execute — только при ALLOW_UPDATE_OPERATION=true

Что может измениться

По умолчанию — ничего: сервер стартует в режиме только чтения. Запись включается по одной операции:

"ALLOW_INSERT_OPERATION": "true",
"ALLOW_UPDATE_OPERATION": "true",
"ALLOW_DELETE_OPERATION": "false"

Что при этом остаётся невозможным:

• DDL — CREATE, ALTER, DROP, TRUNCATE, RENAME — ни при каких настройках.
• Смена базы, SET, CALL, PREPARE, LOAD DATA, блокировки, GRANT и прочее, что меняет смысл следующего запроса или выполняет непроверенный текст.
• SELECT ... INTO OUTFILE — запись файла на сервер базы.
• UPDATE и DELETE без WHERE — требуют явного подтверждения allow_full_table=true в вызове.
• Несколько инструкций в одном вызове — выполняется ровно одна.

Права MySQL — отдельное ограничение поверх этого. Разрешение ALLOW_UPDATE_OPERATION ничего не добавляет пользователю, у которого нет GRANT UPDATE. Рабочая практика: отдельный пользователь с минимальными правами, а не root.

Переменные окружения

Переменная	По умолчанию	Назначение
MYSQL_HOST	127.0.0.1	Хост сервера
MYSQL_PORT	3306	Порт
MYSQL_SOCKET_PATH	—	Unix-сокет вместо host/port
MYSQL_USER	—	Пользователь (обязательно)
MYSQL_PASS	—	Пароль (синоним MYSQL_PASSWORD)
MYSQL_PASS_FILE	—	Прочитать пароль из файла вместо переменной
MYSQL_DB	—	База данных (обязательно, синоним MYSQL_DATABASE)
MYSQL_SSL	false	Требовать TLS
MYSQL_SSL_CA	—	Путь к корневому сертификату; сам по себе включает TLS
MYSQL_SSL_REJECT_UNAUTHORIZED	true	Проверять сертификат сервера
ALLOW_INSERT_OPERATION	false	Разрешить INSERT
ALLOW_UPDATE_OPERATION	false	Разрешить UPDATE
ALLOW_DELETE_OPERATION	false	Разрешить DELETE
MYSQL_MAX_ROWS	1000	Потолок строк в одном ответе
MYSQL_TIMEOUT_MS	30000	Таймаут запроса
MYSQL_CONNECT_TIMEOUT_MS	10000	Таймаут подключения
MYSQL_POOL_SIZE	3	Соединений в пуле
MYSQL_MAX_RETRIES	2	Повторы при обрыве связи и взаимных блокировках
MYSQL_READ_ONLY_TX	true	Выполнять чтение в read-only транзакции
ASKADS_TELEMETRY	—	0 отключает анонимную статистику запусков

Пароль в конфигурации MCP-клиента лежит открытым текстом. MYSQL_PASS_FILE позволяет держать его в файле с нужными правами.

Переход с @benborla29/mcp-server-mysql

Имена переменных совпадают, поэтому достаточно заменить пакет в команде запуска:

-  "args": ["-y", "@benborla29/mcp-server-mysql"]
+  "args": ["-y", "mcp-mysql-client"]

Что изменится в поведении:

• MYSQL_DB обязателен — сервер всегда привязан к одной базе;
• ответы ограничены MYSQL_MAX_ROWS и помечаются truncated;
• DDL недоступен даже при включённых правах на запись;
• UPDATE/DELETE без WHERE требуют подтверждения в вызове;
• набор инструментов другой: query, execute, explain, list_tables, describe_table, server_info.

Диагностика

Первым делом — server_info: он покажет, к чему подключён сервер, какие права у пользователя MySQL и какие ограничения включены.

Симптом	Причина
errno 1045	Неверные MYSQL_USER / MYSQL_PASS
errno 1044	Пользователь есть, прав на базу нет
errno 1142	Не хватает GRANT на операцию или таблицу — ALLOW_* тут не поможет
errno 3159	Сервер требует TLS: MYSQL_SSL=true
ECONNREFUSED / ETIMEDOUT	Хост, порт, файрвол или неподнятый VPN
ER_NOT_SUPPORTED_AUTH_MODE	Нужен TLS для caching_sha2_password
Сервер не подключается	Ошибка конфигурации видна прямо в диалоге: сервер стартует даже без учётных данных и объясняет, чего не хватает

Техническая документация

• Инструменты — параметры и ответы
• Разработка — сборка, тесты, живая проверка
• Публикация — релиз в npm и MCP-реестр
• CLAUDE.md — устройство репозитория для AI-агентов

Лицензия

MIT