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