MySQL MCP Server

Реализация протокола контекста модели (Model Context Protocol, MCP), поддерживающая безопасное взаимодействие с базами данных MySQL. Этот серверный компонент устанавливает связь между AI-приложениями (хост/клиент) и базой данных MySQL, делая исследование и анализ базы данных более безопасными и структурированными через контролируемый интерфейс.

Примечание: MySQL MCP Server поддерживает два режима передачи: стандартный ввод-вывод (STDIO) и Streamable HTTP (SSE). Для удалённого/самостоятельного развёртывания рекомендуется режим SSE.

Способы развёртывания

• Управляемый — Fronteir AI запускает сервер за вас, без локальной настройки.

• Локальный — Smithery устанавливает и запускает сервер на вашей машине.

Related MCP server: MCP MySQL Server

Возможности

• Перечисление доступных таблиц MySQL в виде ресурсов (resources)

• Чтение содержимого таблиц

• Выполнение SQL-запросов с полноценной обработкой ошибок

• Режим нескольких баз данных (опционально MYSQL_DATABASE)

• Поддержка SSE/HTTP-транспорта (MCP_TRANSPORT=sse)

• Поддержка SSH-туннелей

• Полная информация о структуре таблиц

• Выборка данных из таблиц

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

• Полноценное логирование

Установка

Ручная установка

pip install mysql-mcp-server

Установка через Smithery

Используйте Smithery для автоматической установки MySQL MCP Server для Claude Desktop:

npx -y @smithery/cli install designcomputer/mysql-mcp-server --client claude

Установка через Claude Code CLI

claude mcp add --transport stdio designcomputer-mysql_mcp_server uvx mysql_mcp_server

Установка через Autohand Code CLI

autohand mcp add mysql env MYSQL_HOST=localhost MYSQL_PORT=3306 MYSQL_USER=your_username MYSQL_PASSWORD=your_password MYSQL_DATABASE=your_database uvx mysql_mcp_server

Добавление --scope project после mcp add сохранит регистрацию в текущем рабочем пространстве. Актуальные детали CLI см. в Autohand Code.

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

Задайте следующие переменные окружения:

MYSQL_HOST=localhost     # 数据库主机
MYSQL_PORT=3306         # 可选：数据库端口（不指定时默认 3306）
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database # 可选：留空则进入多数据库模式

# 高级配置
MYSQL_SSL_MODE=DISABLED  # DISABLED、REQUIRED、VERIFY_CA、VERIFY_IDENTITY
MYSQL_CONNECT_TIMEOUT=10 # 超时时间（秒）

# 连接行为（可选）
MYSQL_SQL_MODE=TRADITIONAL           # 连接所应用的 SQL mode（默认：TRADITIONAL）

# 兼容性（可选）
MYSQL_CHARSET=utf8mb4
MYSQL_COLLATION=utf8mb4_unicode_ci
MYSQL_AUTH_PLUGIN=       # 例如旧版 MySQL 使用 mysql_native_password
MYSQL_USE_PURE=false     # 强制使用纯 Python 连接器（默认：false）
MYSQL_RAISE_ON_WARNINGS=false        # 出现 SQL 警告时抛出异常（默认：false）

# SSE 传输（可选）
MCP_TRANSPORT=stdio      # stdio 或 sse
MCP_SSE_HOST=0.0.0.0     # 监听所有网卡（Docker/托管部署需要）
PORT=8000                # HTTP 端口（MCP_SSE_PORT 的回退值）
MCP_SSE_ALLOWED_HOSTS=   # 逗号分隔的允许 Host 头（默认：localhost:{port},127.0.0.1:{port}）

# SSH 隧道（可选）
MYSQL_SSH_ENABLE=false   # 设为 true 启用
MYSQL_SSH_HOST=          # SSH 跳板机
MYSQL_SSH_PORT=22        # SSH 端口
MYSQL_SSH_USER=          # SSH 用户名
MYSQL_SSH_KEY_PATH=      # SSH 私钥路径
MYSQL_SSH_REMOTE_HOST=localhost # 从跳板机视角看的目标主机
MYSQL_SSH_REMOTE_PORT=3306
MYSQL_LOCAL_PORT=3330

Загрузка файла .env

При запуске сервер автоматически загружает файл .env через python-dotenv, для локального использования достаточно:

cp .env.example .env   # 然后填入你的凭据

Файл читается из рабочего каталога процесса (и его родительских каталогов), поэтому при самостоятельном запуске сервера в каталоге проекта всё работает корректно.

⚠️ Claude Code / Claude Desktop: Эти хосты запускают сервер из своих собственных рабочих каталогов, поэтому не находят .env из проекта, и вы увидите Missing required database configuration. Запишите значения MYSQL_* в блок env конфигурации MCP (см. раздел «Использование» ниже), не полагаясь на .env.

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

Если MYSQL_DATABASE не задан, сервер переходит в режим нескольких баз данных:

• list_resources возвращает все пользовательские базы данных (системные базы фильтруются)

• В SQL-запросах используйте полные имена таблиц, например mydb.mytable

• Примечание: поддерживается только один SQL-оператор, многооператорные запросы не поддерживаются (например, USE db; SELECT ...).

Административная страница и псевдонимы нескольких баз данных (режим SSE)

Запустите сервер в режиме SSE и откройте встроенную административную страницу для управления несколькими подключениями к базам данных, для каждого подключения можно настроить отдельные учётные записи чтения/записи:

# Windows PowerShell
$env:MCP_TRANSPORT="sse"; $env:MCP_SSE_PORT="8000"; python -m mysql_mcp_server
# Linux/macOS
MCP_TRANSPORT=sse MCP_SSE_PORT=8000 python -m mysql_mcp_server

Административная страница: http://127.0.0.1:8000/admin/ (доступ только через loopback — административный API и страница отклоняют не-loopback клиентов и неизвестные заголовки Host; не размещайте её за обратным прокси).

Для каждого псевдонима можно настроить:

Клиенты подключаются по псевдониму: http://127.0.0.1:8000/sse?alias=db1 (при отсутствии alias используется псевдоним по умолчанию). Когда в config/databases.json нет ни одной записи, исходные переменные окружения MYSQL_* по-прежнему работают как обратно совместимый резервный вариант для одной базы данных (в этом режиме чтение и запись используют одну учётную запись).

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

Как подтверждаются операции записи: сервер выполняет трёхуровневую оценку каждого оператора (чтение / запись / удаление). Операции чтения выполняются с учётной записью запросов; операции записи и удаления вызывают MCP elicitation-окно с полным SQL — при принятии выполняется с учётной записью операций, при отклонении прерывается. Если клиент не поддерживает elicitation, поведение определяется политикой write_policy псевдонима (см. таблицу выше). Все попытки операций записи фиксируются в списке аудита административной страницы (на диске — logs/audit.log).

Доступные инструменты

execute_sql

Выполняет произвольные стандартные SQL-запросы.

• Параметры: query (строка)

• Функциональность: поддерживает SELECT, SHOW, DESCRIBE и DML (INSERT, UPDATE, DELETE). DML-операции помечены как деструктивные.

• Ограничения: поддерживается только один оператор, многооператорные запросы не поддерживаются.

• Межбазовый доступ: независимо от настройки MYSQL_DATABASE, можно запрашивать любую базу данных через запись database.table.

get_schema_info

Предоставляет подробные метаданные о структуре базы данных.

• Параметры: table_name (необязательная строка)

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

• Межбазовый доступ: передача database.table позволяет запрашивать базы за пределами MYSQL_DATABASE; голое имя таблицы использует настроенную базу данных.

• Правила идентификаторов: имена могут содержать только буквенно-цифровые символы, подчёркивания и $ (допускается одна точка как разделитель database.table).

get_table_sample

Получает репрезентативную выборку данных.

• Параметры: table_name (строка), limit (необязательное целое, максимум 20)

• Назначение: быстрое понимание формата и содержания данных без загрузки больших результирующих наборов.

• Межбазовый доступ: передача database.table позволяет выполнять выборку из баз за пределами MYSQL_DATABASE; голое имя таблицы использует настроенную базу данных.

• Правила идентификаторов: имена могут содержать только буквенно-цифровые символы, подчёркивания и $ (допускается одна точка как разделитель database.table).

Доступные подсказки (Prompts)

Помимо инструментов, сервер предоставляет MCP prompts — управляемые многошаговые рабочие процессы, которые клиент может запускать по требованию. В Claude Code они появляются как слэш-команды (/mcp__<server>__<prompt>); в Claude Desktop — в меню подсказок (+).

Пример (Claude Code):

/mcp__mysql__explore_database
/mcp__mysql__analyze_table customers

Обе подсказки используют существующие инструменты get_schema_info и get_table_sample; explore_database также использует список ресурсов для перечисления таблиц.

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

С Claude Desktop

Добавьте следующее в claude_desktop_config.json:

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mysql_mcp_server",
        "run",
        "mysql_mcp_server"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Более подробные примеры и инструкции для конкретных агентов см. в MCP_USECASES.md.

С Visual Studio Code

Добавьте следующее в mcp.json:

{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mysql-mcp-server",
        "mysql_mcp_server"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Примечание: необходимо предварительно установить uv.

Отладка с MCP Inspector

MySQL MCP Server не предназначен для автономного запуска или прямого запуска из командной строки Python, но вы можете использовать MCP Inspector для отладки.

MCP Inspector предоставляет удобный способ тестирования и отладки MCP-реализаций:

# 安装依赖
pip install -r requirements.txt
# 使用 MCP Inspector 调试（不要直接用 Python 运行）

MySQL MCP Server предназначен для интеграции в AI-приложения, такие как Claude Desktop, и не должен запускаться как самостоятельная Python-программа.

Разработка

# 克隆仓库
git clone https://github.com/designcomputer/mysql_mcp_server.git
cd mysql_mcp_server
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows 上用 `venv\Scripts\activate`
# 安装开发依赖
pip install -r requirements-dev.txt
# 复制示例配置并填入你的凭据
cp .env.example .env
# 编辑 .env，填入 MySQL 连接信息
# 运行测试
pytest

Меры безопасности

• Проверка идентификаторов: имена таблиц и баз, передаваемые в get_schema_info и get_table_sample, проходят строгую проверку по белому списку (допускаются только буквенно-цифровые символы, подчёркивания и $; допускается одна точка как разделитель database.table). Все остальные специальные символы отклоняются для предотвращения SQL-инъекций.

• Зашифрованный доступ: полная поддержка SSL/TLS и SSH-туннелей для безопасных удалённых подключений.

• Конфиденциальность журналов: пароли и SSH-ключи автоматически маскируются в журналах сервера.

• Минимальные привилегии: всегда используйте выделенного пользователя MySQL с минимальными привилегиями.

• SSE-транспорт не имеет встроенной аутентификации. SSE-сервер по умолчанию привязывается к 0.0.0.0 и принимает подключения без учётных данных. Если он доступен за пределами localhost, разместите его за обратным прокси с обязательной аутентификацией (nginx, Caddy, Traefik). Пример nginx + HTTP Basic Auth:

  location /sse {
      auth_basic "MCP";
      auth_basic_user_file /etc/nginx/.htpasswd;
      proxy_pass http://127.0.0.1:8000;
      proxy_set_header Host $host;
      proxy_buffering off;
  }
  location /messages/ {
      auth_basic "MCP";
      auth_basic_user_file /etc/nginx/.htpasswd;
      proxy_pass http://127.0.0.1:8000;
      proxy_set_header Host $host;
  }

  Установите MCP_SSE_HOST=127.0.0.1, чтобы сервер прослушивал только loopback-адрес, и прокси станет единственной публичной точкой входа. Установите MCP_SSE_ALLOWED_HOSTS на публичное имя хоста, пересылаемое прокси (например, MCP_SSE_ALLOWED_HOSTS=myserver.example.com:443).

Полное руководство по безопасному развёртыванию см. в SECURITY.md.

Рекомендации по безопасности

Эта MCP-реализация требует доступа к базе данных для работы. Для безопасности:

1. Создайте выделенного пользователя MySQL с минимальными привилегиями

2. Никогда не используйте root-учётные данные или учётные записи администратора

3. Ограничьте доступ к базе данных только необходимыми операциями

4. Включите логирование для аудита

5. Регулярно проводите проверки безопасности доступа к базе данных

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

• Создание ограниченного пользователя MySQL

• Настройка соответствующих привилегий

• Мониторинг доступа к базе данных

• Рекомендации по безопасности

⚠️ Важно: при настройке доступа к базе данных обязательно соблюдайте принцип минимальных привилегий.

Лицензия

MIT License — подробности см. в файле LICENSE.

Участие в разработке

1. Форкните этот репозиторий

2. Создайте ветку функции (git checkout -b feature/amazing-feature)

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

4. Отправьте ветку (git push origin feature/amazing-feature)

5. Откройте Pull Request