MySQL MCP

io.github.gistrecPublished by GitHub account gistrecv1.1.1Updated Nov 5, 2026

MCP server for one MySQL database: schema, read-only queries and guarded writes.

VerifiedSTDIODesktop onlyDatabasesData & Analytics

Overview

AI-generated overview

Local MCP server bound to one MySQL or MariaDB database, letting an assistant inspect schema, run read-only queries and plans, and optionally perform guarded…

What you can do
  • Inspect connection, user, MySQL grants and server limits
  • List tables and views with engine, size and row estimates
  • Describe table columns, indexes and foreign keys in both directions
  • Run a single read-only query with bound parameters and a row cap
  • Show the execution plan of a read query, optionally with real timing
  • Run one INSERT, UPDATE, DELETE or REPLACE when writes are enabled
When to use it
Useful when you want an assistant to explore a specific MySQL or MariaDB database, answer data questions in natural language, or diagnose slow queries, with read-only access by default. Add it when you are comfortable pointing it at one database with a least-privilege account.
Requirements
Runs locally via npx (Node.js). Needs MYSQL_USER and MYSQL_DB, plus host, port or socket and credentials; MYSQL_PASS or MYSQL_PASS_FILE for the password. Network access to the database server; MYSQL_SSL or MYSQL_SSL_CA for TLS. Write access requires ALLOW_INSERT_OPERATION, ALLOW_UPDATE_OPERATION or ALLOW_DELETE_OPERATION and a restart.
Before you install
The password sits in plain text in the client config unless MYSQL_PASS_FILE is used. Writes are enabled by environment variables and execute immediately without a transaction, so they cannot be rolled back from the server; UPDATE and DELETE without WHERE need explicit confirmation. DDL is never allowed. MySQL grants still apply on top. The README mentions anonymous telemetry of tool names and outcomes, disabled with ASKADS_TELEMETRY=0.

Installation

In SourceWeft

  1. Open MySQL MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

MySQL MCP

[npm] [CI] [License: MIT]

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

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

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

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

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

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

Claude Code:

bash
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:

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

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

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

json
"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_HOST127.0.0.1Хост сервера
MYSQL_PORT3306Порт
MYSQL_SOCKET_PATH—Unix-сокет вместо host/port
MYSQL_USER—Пользователь (обязательно)
MYSQL_PASS—Пароль (синоним MYSQL_PASSWORD)
MYSQL_PASS_FILE—Прочитать пароль из файла вместо переменной
MYSQL_DB—База данных (обязательно, синоним MYSQL_DATABASE)
MYSQL_SSLfalseТребовать TLS
MYSQL_SSL_CA—Путь к корневому сертификату; сам по себе включает TLS
MYSQL_SSL_REJECT_UNAUTHORIZEDtrueПроверять сертификат сервера
ALLOW_INSERT_OPERATIONfalseРазрешить INSERT
ALLOW_UPDATE_OPERATIONfalseРазрешить UPDATE
ALLOW_DELETE_OPERATIONfalseРазрешить DELETE
MYSQL_MAX_ROWS1000Потолок строк в одном ответе
MYSQL_TIMEOUT_MS30000Таймаут запроса
MYSQL_CONNECT_TIMEOUT_MS10000Таймаут подключения
MYSQL_POOL_SIZE3Соединений в пуле
MYSQL_MAX_RETRIES2Повторы при обрыве связи и взаимных блокировках
MYSQL_READ_ONLY_TXtrueВыполнять чтение в read-only транзакции
ASKADS_TELEMETRY—0 отключает анонимную статистику запусков и вызовов инструментов (имя инструмента и исход: успех или категория ошибки с кодом ошибки MySQL, без текста ошибки)

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

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

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

diff
-  "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
Сервер не подключаетсяОшибка конфигурации видна прямо в диалоге: сервер стартует даже без учётных данных и объясняет, чего не хватает

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

Лицензия

MIT

Source: README.md at commit 39810eb

Tools

6

server_info

Сведения о подключении и правах

Показывает, к какой базе и под каким пользователем подключён сервер, версию MySQL, размер базы, выданные пользователю права (GRANT) и действующие ограничения самого MCP-сервера: разрешённые операции записи, потолок строк в ответе и таймаут запроса. Стоит вызвать первым, если непонятно, почему запрос отклонён: права MySQL и разрешения сервера — это два независимых ограничения.

Takes no parameters.

list_tables

Список таблиц базы

Перечисляет таблицы и представления подключённой базы: движок, кодировку, комментарий, размер данных и индексов в байтах и оценку числа строк. Оценка берётся из статистики InnoDB и может заметно расходиться с реальностью — точное число даёт COUNT(*) через query. С этого инструмента стоит начинать знакомство с незнакомой базой.

Takes no parameters.

describe_table

Структура таблицы

Показывает структуру таблицы: столбцы с типами, обнуляемостью, значениями по умолчанию и комментариями, индексы с их составом, внешние ключи наружу и, главное, ссылки на эту таблицу из других (referenced_by) — именно они определяют, безопасно ли удалять строки. Разделы, кроме столбцов, можно отключить, если нужен только их список.

Parameterstablerequiredinclude_indexesinclude_foreign_keys

query

Выполнить читающий SQL-запрос

Выполняет один читающий запрос (SELECT, SHOW, DESCRIBE, WITH ... SELECT) и возвращает строки. Изменяющие запросы отклоняются даже при включённых правах на запись — для них есть execute. Запрос идёт внутри read-only транзакции, число строк ограничено MYSQL_MAX_ROWS: если ответ обрезан, поле truncated равно true и это префикс, а не весь результат. Значения подставляйте через ? и params — драйвер экранирует их сам.

Parameterssqlrequiredlimitparams

explain

Показать план выполнения запроса

Возвращает план выполнения читающего запроса: какие индексы будут использованы и сколько строк сервер рассчитывает просмотреть. Обычный режим ничего не выполняет; analyze=true запускает запрос по-настоящему и показывает фактическое время — на больших таблицах это дорого. Полезно перед тяжёлой выборкой и при диагностике медленных запросов.

Parameterssqlrequiredformatparamsanalyze

execute

Выполнить изменяющий SQL-запрос

Выполняет один изменяющий запрос — INSERT, UPDATE, DELETE или REPLACE — и возвращает число затронутых строк. Сейчас сервер разрешает: только чтение. Права выдаются переменными ALLOW_INSERT_OPERATION, ALLOW_UPDATE_OPERATION и ALLOW_DELETE_OPERATION в конфигурации MCP-клиента и требуют перезапуска сервера — из диалога их получить нельзя. DDL (CREATE, ALTER, DROP, TRUNCATE) не поддерживается ни при каких настройках. Запрос выполняется сразу и без транзакции: откатить его отсюда нельзя. UPDATE и DELETE без WHERE и LIMIT требуют явного allow_full_table=true.

Parameterssqlrequiredparamsallow_full_table

Version history

4
  1. v1.1.1LatestNov 5, 2026
  2. v1.1.0Oct 31, 2026
  3. v1.0.1Oct 22, 2026
  4. v1.0.0Sep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts