mysql-mcp-server

Сервер Model Context Protocol (MCP), который позволяет клиенту MCP (Claude Desktop, Claude Code и т.д.) выполнять SQL-запросы к базе данных MySQL через четыре инструмента: select, insert, update и delete.

Сервер работает как Python-пакет под управлением uv и взаимодействует с клиентом через stdio, запускаясь как подпроцесс клиента.

Требования

• Python 3.11+

• uv

• Доступный сервер MySQL

Related MCP server: Universal Database MCP Server

Установка

uv sync

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

Серверу требуется шесть значений, каждое из которых можно задать через переменную окружения и/или флаг CLI (флаги CLI имеют приоритет над переменными окружения):

Если обязательное значение отсутствует или MYSQL_MODE не равен readonly/readwrite, сервер выводит сообщение об ошибке в stderr и завершает работу с кодом 1, не запускаясь.

• Режим readonly: разрешён только инструмент select. Инструменты insert/update/delete отклоняются с ошибкой PERMISSION_DENIED.

• Режим readwrite: разрешены все четыре инструмента.

Режим фиксируется на всё время работы процесса; его нельзя изменить во время выполнения.

Рекомендация по безопасности: режим readonly — это защита на уровне приложения, а не замена ограничениям прав на стороне базы данных. По возможности в режиме readonly подключайтесь к MySQL под учётной записью, у которой есть только права SELECT.

Нужен ли файл .env? Нет. Сервер сам никогда не читает файлы .env — он читает только флаги CLI и реальные переменные окружения процесса (os.environ). То, как вы передаёте значения в это окружение, зависит от способа запуска:

• В качестве MCP-сервера (см. Подключение к MCP-клиенту ниже): клиент (Claude Desktop/Code) запускает серверный процесс и передаёт блок env из своего JSON-конфига напрямую как переменные окружения. Файл .env не нужен и не используется.

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

  uv run --env-file .env mysql-mcp-server

  Файл .env игнорируется git и никогда не должен попадать в репозиторий.

Запуск

# Environment variables (or use `uv run --env-file .env mysql-mcp-server`, see above)
export MYSQL_MODE=readonly
export MYSQL_HOST=127.0.0.1
export MYSQL_PORT=3306
export MYSQL_USER=app_user
export MYSQL_PASSWORD=secret
export MYSQL_DATABASE=mydb
uv run mysql-mcp-server

# Or, equivalently, via CLI flags
uv run mysql-mcp-server \
  --mysql-mode readonly \
  --mysql-host 127.0.0.1 \
  --mysql-port 3306 \
  --mysql-user app_user \
  --mysql-password secret \
  --mysql-database mydb

Подключение к MCP-клиенту

Claude Desktop / Claude Code

Добавьте запись в конфиг сервера вашего MCP-клиента (например, в claude_desktop_config.json у Claude Desktop или в .mcp.json у Claude Code):

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mysql-mcp-server",
        "run",
        "mysql-mcp-server"
      ],
      "env": {
        "MYSQL_MODE": "readonly",
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "app_user",
        "MYSQL_PASSWORD": "secret",
        "MYSQL_DATABASE": "mydb"
      }
    }
  }
}

Перезапустите клиент после изменения конфига. Инструменты select, insert, update и delete (в зависимости от MYSQL_MODE) должны стать доступны модели.

Инструменты

Все четыре инструмента принимают {"query": string, "params"?: array} и всегда используют плейсхолдеры %s в запросе — никогда не подставляйте пользовательский ввод в строку запроса напрямую.

Каждый вызов инструмента возвращает одно из:

{ "success": true, "data": { ... } }

{ "success": false, "error": { "code": "...", "message": "..." } }

Коды ошибок: PERMISSION_DENIED, INVALID_QUERY_TYPE, MULTI_STATEMENT_NOT_ALLOWED, DB_CONNECTION_ERROR, DB_EXECUTION_ERROR, INTERNAL_ERROR.

Многооператорные запросы (разделённые ;) и любые операторы DDL/привилегий (DROP, TRUNCATE, ALTER, GRANT, CREATE USER, ...) всегда отклоняются, поскольку принимаются только четыре перечисленных выше типа операторов.

Разработка

uv sync
uv run ruff format .
uv run ruff check .
uv run pytest -v
uv run uv build   # packaging check

Устранение неполадок

• Сервер сразу завершается с кодом 1: отсутствует обязательное значение MYSQL_* или MYSQL_MODE задан неверно — проверьте сообщение в stderr.

• DB_CONNECTION_ERROR: MySQL недоступен или неверные учётные данные. Сервер продолжает работать и повторит подключение при следующем вызове инструмента.

• PERMISSION_DENIED при insert/update/delete: сервер работает в режиме readonly; перезапустите его с MYSQL_MODE=readwrite, если запись действительно нужна.

История версий

• 0.1.0 — Начальный релиз: инструменты select/insert/update/delete, политика режимов readonly/readwrite, stdio-транспорт MCP, автоматическое повторное подключение и повтор запроса при потере соединения.