MySQL MCP Server
secretjiang42/mysql-mcp-server
MCP server para MySQL com controles de segurança e execução de SQL parametrizado
Ver no GitHubServidor MCP reutilizável para integrar MySQL com agentes de IA e Claude. Fornece ferramentas para consultar, executar comandos SQL, inspecionar schema e gerenciar conexões com controles de segurança robustos. Configuração via variáveis de ambiente, suporta TLS e permissões granulares.
Instalação
npx convez-ai secretjiang42/mysql-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Conectar Claude a bancos de dados MySQL para análise e extração de dados
- Automatizar scripts de migração e manutenção de banco de dados via agentes IA
- Auditar schemas e executar queries read-only de forma segura em produção
Veredito

MCP server bem estruturado com foco em segurança (write-only em modo explícito, query timeout, SSL). Ideal para quem precisa expor MySQL a agentes Claude de forma controlada; exige Python 3.11+ e gestão cuidadosa de permissões de banco.
README
A tradução para o português deste README ainda está na fila.
MySQL MCP Server
A reusable Model Context Protocol server for MySQL.
This repo is intended to be easy for another AI agent or developer to install, inspect, and configure. All connection settings come from environment variables.
What It Provides
get_connection_info: show sanitized connection/config status.ping: verify the MCP server process is alive.ping_db: verify MySQL connectivity.show_databases: list databases visible to the configured user.list_tables: list tables in a database.describe_table: inspect columns for one table.sql_query: run parameterized read-only SQL.sql_execute: run parameterized write SQL only when explicitly enabled.
Libraries
Use Python 3.11+ with:
mcp: official Python SDK for FastMCP servers.pymysql: pure-Python MySQL client.cryptography: TLS/auth support used by PyMySQL in common MySQL deployments.pytest: tests.ruff: linting.pip-audit: dependency audit.
This project is licensed under MIT. Direct third-party dependency license notes are in THIRD_PARTY_NOTICES.md.
The MIT License already includes a broad "AS IS" warranty disclaimer and
limitation of liability. This project also includes a project-specific risk
notice in LICENSE and operational guidance in SECURITY.md because MCP
clients and AI agents can execute database tools incorrectly. You are
responsible for database permissions, backups, restores, audit logging, model
behavior, and human approval workflows around any database connected to this
server.
Install
git clone https://github.com/secretjiang42/mysql-mcp-server.git
cd mysql-mcp-server
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
No secrets are committed. Start from .env.example only as a reference.
Use the repo virtual environment's Python for local runs, tests, and MCP config. Do not rely on a global python; another package named mysql_mcp_server may already be installed globally and can cause misleading imports or test failures.
Environment Variables
Required at startup:
MYSQL_MCP_USER=your_user
MYSQL_MCP_PASSWORD=your_password
MYSQL_MCP_PASSWORD must be set, but it may be set to an empty string for local accounts with no password.
Connection settings:
MYSQL_MCP_HOST=127.0.0.1
MYSQL_MCP_PORT=3306
MYSQL_MCP_DATABASE=optional_default_database
MYSQL_MCP_HOST defaults to 127.0.0.1. MYSQL_MCP_PORT defaults to 3306. MYSQL_MCP_DATABASE is optional, but database-specific tools such as list_tables and describe_table need either MYSQL_MCP_DATABASE or a database argument.
Security controls:
MYSQL_MCP_SSL=false
MYSQL_MCP_SSL_VERIFY=true
MYSQL_MCP_SSL_CA_CERT=
MYSQL_MCP_SSL_CAPATH=
MYSQL_MCP_SSL_CLIENT_CERT=
MYSQL_MCP_SSL_CLIENT_KEY=
MYSQL_MCP_ALLOW_WRITES=false
MYSQL_MCP_MAX_ROWS=200
MYSQL_MCP_CONNECT_TIMEOUT=10
MYSQL_MCP_QUERY_TIMEOUT=30
MYSQL_MCP_CONNECT_TIMEOUT and MYSQL_MCP_QUERY_TIMEOUT are in seconds. The query timeout applies to each read/write on the connection, so a runaway query fails instead of hanging the tool call. Raise it if you expect slow analytical queries.
MYSQL_MCP_SSL=false is the default because local development usually connects to 127.0.0.1, localhost, a Unix socket, or a Cloud SQL/Auth Proxy style local tunnel. That is not appropriate for direct remote database connections.
For any direct connection across a network you do not fully control, set:
MYSQL_MCP_SSL=true
MYSQL_MCP_SSL_VERIFY=true
MYSQL_MCP_SSL_CA_CERT=C:\Users\YOUR_USER\.mysql-certs\ca.pem
Without TLS, MySQL credentials and query results can be exposed to network observers. Without certificate verification, TLS encryption may still be vulnerable to impersonation or man-in-the-middle attacks.
Where To Put PEM Files
Do not commit PEM files.
Recommended local locations:
Windows:
C:\Users\YOUR_USER\.mysql-certs\ca.pem
C:\Users\YOUR_USER\.mysql-certs\client-cert.pem
C:\Users\YOUR_USER\.mysql-certs\client-key.pem
macOS/Linux:
~/.mysql-certs/ca.pem
~/.mysql-certs/client-cert.pem
~/.mysql-certs/client-key.pem
Set filesystem permissions so only the current user can read private keys. If a provider gives a CA bundle, pass that bundle as MYSQL_MCP_SSL_CA_CERT.
Run Locally
PowerShell example:
$env:MYSQL_MCP_HOST = '127.0.0.1'
$env:MYSQL_MCP_PORT = '3306'
$env:MYSQL_MCP_USER = 'app_user'
$env:MYSQL_MCP_PASSWORD = 'set-this-outside-git'
$env:MYSQL_MCP_DATABASE = 'app_db'
$env:MYSQL_MCP_SSL = 'false'
$env:MYSQL_MCP_ALLOW_WRITES = 'false'
python -m mysql_mcp_server
The server uses stdio transport by default.
Configure Codex
Add a server entry to your Codex MCP config. Keep secrets in the environment or a local secret manager, not in the repo.
Prefer the absolute path to the virtual environment's Python executable so Codex can import this package reliably.
This is important on machines where a different mysql_mcp_server package may already be installed in the global Python environment.
Windows example:
[mcp_servers.mysql_mcp]
command = "C:/path/to/mysql-mcp-server/.venv/Scripts/python.exe"
args = ["-m", "mysql_mcp_server"]
startup_timeout_sec = 30
[mcp_servers.mysql_mcp.env]
MYSQL_MCP_HOST = "127.0.0.1"
MYSQL_MCP_PORT = "3306"
MYSQL_MCP_USER = "app_user"
MYSQL_MCP_DATABASE = "app_db"
MYSQL_MCP_SSL = "false"
MYSQL_MCP_ALLOW_WRITES = "false"
macOS/Linux command path example:
command = "/path/to/mysql-mcp-server/.venv/bin/python"
If your MCP client process was already running when you changed environment variables, restart the client so it inherits the new values.
Query Parameters
sql_query and sql_execute accept params_json, a JSON array or object passed to PyMySQL parameter substitution.
Use %s placeholders:
SELECT id, email
FROM users
WHERE status = %s
LIMIT 10
With:
["active"]
sql_query uses a conservative first-keyword allowlist: SELECT, SHOW, DESCRIBE, DESC, and EXPLAIN. Queries beginning with WITH are intentionally rejected because CTEs can lead into mutating statements; use a plain SELECT or add a real SQL parser before enabling CTE support. EXPLAIN ANALYZE is also rejected because MySQL executes the analyzed statement, which can mutate data when it is an UPDATE or DELETE.
This is keyword filtering, not SQL parsing. It does not block statements with side effects that begin with an allowed keyword, such as SELECT ... INTO OUTFILE or SELECT calls to stored functions that write data. Use a least-privilege read-only MySQL account as the primary protection.
Write Safety
Writes are disabled by default. sql_execute raises an explicit error unless:
MYSQL_MCP_ALLOW_WRITES=true
Even with writes enabled, the calling agent should preview target rows first and ask for explicit confirmation before running INSERT, UPDATE, DELETE, DDL, or other mutating statements.
AI-generated SQL can be wrong. Before enabling writes against important data, use a dedicated least-privilege database account, make a backup, verify restore procedures, and confirm the exact database, table, filter, and expected target row count. Do not rely on an AI model as the only approval layer for irreversible changes.
Verify
Activate the repo virtual environment first, then run:
ruff check .
pytest
python -m pip_audit
pip-audit may need network access to check current vulnerability data. The
repository also runs automated pip-audit and OSV-Scanner checks in GitHub
Actions.
Skill Package
This repo includes an installable Codex skill package at:
packages/mysql-mcp-codex-skill/
Install the skill by placing the whole packages/mysql-mcp-codex-skill folder in your Codex skills directory and naming the destination folder mysql-mcp. Do not copy only the text from SKILL.md; Codex discovers skills by folder.
Examples:
C:\Users\YOUR_USER\.codex\skills\mysql-mcp
~/.codex/skills/mysql-mcp
Restart Codex after copying the skill.