convez.ai
MCP ServerIntegração & APIsIntermediário
secretjiang42

MySQL MCP Server

secretjiang42/mysql-mcp-server

MCP server para MySQL com controles de segurança e execução de SQL parametrizado

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-server

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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.

Ver o original no GitHub

Bom para

Relacionados