MySQL

Integração com banco de dados MySQL com controles

Documentação

Servidor MCP MySQL

Uma implementação do Model Context Protocol (MCP) que permite interação segura com bancos de dados MySQL. Este componente de servidor facilita a comunicação entre aplicações de IA (hosts/clientes) e bancos de dados MySQL, tornando a exploração e análise de bancos de dados mais segura e estruturada por meio de uma interface controlada.

Nota: O Servidor MCP MySQL suporta tanto os modos de transporte padrão de entrada/saída (STDIO) quanto HTTP Streamable (SSE). O modo SSE é recomendado para implantações remotas/self-hosted.

Opções de implantação

Hospedado — Fronteir AI executa o servidor para você; nenhuma configuração local é necessária.
Local — Smithery instala e executa o servidor na sua própria máquina.

Recursos

Listar tabelas MySQL disponíveis como recursos
Ler o conteúdo das tabelas
Executar consultas SQL com tratamento adequado de erros
Modo multi-banco de dados (Opcional MYSQL_DATABASE)
Suporte a transporte SSE/HTTP (MCP_TRANSPORT=sse)
Suporte a túnel SSH
Informações abrangentes de esquema
Amostragem de dados de tabelas
Acesso seguro ao banco de dados por meio de variáveis de ambiente
Registro de logs abrangente

Instalação

Instalação Manual

pip install mysql-mcp-server

Instalação via Smithery

Para instalar o Servidor MCP MySQL para Claude Desktop automaticamente via Smithery:

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

Instalação via CLI do Claude Code

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

Instalação via CLI do Autohand Code

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

Adicione --scope project após mcp add para manter o registro no espaço de trabalho atual. Consulte Autohand Code para obter detalhes atuais da CLI.

Configuração

Defina as seguintes variáveis de ambiente:

MYSQL_HOST=localhost     # Database host
MYSQL_PORT=3306         # Optional: Database port (defaults to 3306 if not specified)
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database # Optional: Omit for multi-database mode

# Advanced Configuration
MYSQL_SSL_MODE=DISABLED  # DISABLED, REQUIRED, VERIFY_CA, VERIFY_IDENTITY
MYSQL_CONNECT_TIMEOUT=10 # Timeout in seconds

# Connection behaviour (Optional)
MYSQL_SQL_MODE=TRADITIONAL           # SQL mode applied to the connection (default: TRADITIONAL)

# Compatibility (Optional)
MYSQL_CHARSET=utf8mb4
MYSQL_COLLATION=utf8mb4_unicode_ci
MYSQL_AUTH_PLUGIN=       # e.g., mysql_native_password for older MySQL versions
MYSQL_USE_PURE=false     # Force the pure-Python connector (default: false)
MYSQL_RAISE_ON_WARNINGS=false        # Raise on SQL warnings (default: false)

# SSE Transport (Optional)
MCP_TRANSPORT=stdio      # stdio or sse
MCP_SSE_HOST=0.0.0.0     # Listen on all interfaces (required for Docker/hosting)
PORT=8000                # HTTP port (fallback for MCP_SSE_PORT)
MCP_SSE_ALLOWED_HOSTS=   # Comma-separated allowed Host headers (default: localhost:{port},127.0.0.1:{port})

# SSH Tunneling (Optional)
MYSQL_SSH_ENABLE=false   # Set to true to enable
MYSQL_SSH_HOST=          # SSH jump host
MYSQL_SSH_PORT=22        # SSH port
MYSQL_SSH_USER=          # SSH username
MYSQL_SSH_KEY_PATH=      # Path to SSH private key
MYSQL_SSH_REMOTE_HOST=localhost # Host from the perspective of the jump host
MYSQL_SSH_REMOTE_PORT=3306
MYSQL_LOCAL_PORT=3330

Carregamento do arquivo `.env`

Na inicialização, o servidor carrega automaticamente um arquivo .env via python-dotenv, portanto, para uso local, você pode simplesmente:

cp .env.example .env   # then edit with your credentials

O arquivo é lido do diretório de trabalho do processo (e diretórios pai), o que funciona quando você executa o servidor a partir da pasta do projeto.

⚠️ Claude Code / Claude Desktop: esses hosts iniciam o servidor a partir do próprio diretório de trabalho, portanto, o .env do projeto não será encontrado e você verá Missing required database configuration. Coloque seus valores de MYSQL_* no bloco env da configuração MCP (mostrado na seção Uso abaixo) em vez de depender de .env.

Modo Multi-Banco de Dados

Quando MYSQL_DATABASE não está definido, o servidor opera no modo multi-banco de dados:

list_resources retorna todos os bancos de dados do usuário (bancos de dados do sistema são filtrados)
Use nomes de tabela totalmente qualificados como mydb.mytable em consultas SQL
Nota: Apenas instruções SQL únicas são suportadas. Consultas com múltiplas instruções (por exemplo, USE db; SELECT ...) não são suportadas.

Ferramentas Disponíveis

`execute_sql`

Executa qualquer consulta SQL padrão.

Argumentos: query (string)
Recursos: Suporta SELECT, SHOW, DESCRIBE e DML (INSERT, UPDATE, DELETE). Operações DML são marcadas com um aviso de destrutividade.
Limitação: Apenas instruções únicas. Consultas com múltiplas instruções não são suportadas.
Entre bancos de dados: Use a notação database.table para consultar qualquer banco de dados, independentemente da configuração de MYSQL_DATABASE.

`get_schema_info`

Fornece metadados detalhados sobre estruturas de banco de dados.

Argumentos: table_name (string opcional)
Saída: Nomes de colunas, tipos, nulabilidade, valores padrão e comentários.
Entre bancos de dados: Passe database.table para consultar uma tabela fora de MYSQL_DATABASE; nomes simples usam o banco de dados configurado.
Regras de identificador: Os nomes devem conter apenas caracteres alfanuméricos, sublinhados e $ (pontos são permitidos como separador entre nomes de banco de dados e tabela).

`get_table_sample`

Busca uma amostra representativa de dados.

Argumentos: table_name (string), limit (inteiro opcional, máx. 20)
Caso de uso: Entender rapidamente formatos e conteúdo de dados sem buscar grandes conjuntos de resultados.
Entre bancos de dados: Passe database.table para amostrar uma tabela fora de MYSQL_DATABASE; nomes simples usam o banco de dados configurado.
Regras de identificador: Os nomes devem conter apenas caracteres alfanuméricos, sublinhados e $ (pontos são permitidos como separador entre nomes de banco de dados e tabela).

Prompts Disponíveis

Além das ferramentas, o servidor expõe prompts MCP — fluxos de trabalho guiados em várias etapas que um cliente pode iniciar sob demanda. No Claude Code, eles aparecem como comandos de barra (/mcp__<server>__<prompt>); no Claude Desktop, aparecem no menu de prompts (+).

Prompt	Argumentos	Descrição
`explore_database`	(nenhum)	Explorar o banco de dados sistematicamente: descobrir tabelas disponíveis, inspecionar seus esquemas, amostrar os dados e resumir o que existe.
`analyze_table`	`table_name` (obrigatório)	Aprofundar-se em uma tabela específica: recuperar seu esquema, amostrar seus dados e sugerir consultas úteis. Aceita notação `database.table` para consultas entre bancos de dados.

Exemplo (Claude Code):

/mcp__mysql__explore_database
/mcp__mysql__analyze_table customers

Ambos os prompts orquestram as ferramentas existentes get_schema_info e get_table_sample; explore_database também usa a listagem de recursos para enumerar tabelas.

Uso

Com Claude Desktop

Adicione isto ao seu 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"
      }
    }
  }
}

Para exemplos mais detalhados e orientação específica para agentes, consulte MCP_USECASES.md.

Com Visual Studio Code

Adicione isto ao seu 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"
      }
    }
  }
}

Nota: Será necessário instalar o uv para que isso funcione

Depuração com MCP Inspector

Embora o Servidor MCP MySQL não seja destinado a ser executado de forma autônoma ou diretamente da linha de comando com Python, você pode usar o MCP Inspector para depurá-lo.

O MCP Inspector fornece uma maneira conveniente de testar e depurar sua implementação MCP:

# Install dependencies
pip install -r requirements.txt
# Use the MCP Inspector for debugging (do not run directly with Python)

O Servidor MCP MySQL é projetado para ser integrado a aplicações de IA como Claude Desktop e não deve ser executado diretamente como um programa Python autônomo.

Desenvolvimento

# Clone the repository
git clone https://github.com/designcomputer/mysql_mcp_server.git
cd mysql_mcp_server
# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
# Install development dependencies
pip install -r requirements-dev.txt
# Copy the example config and edit with your credentials
cp .env.example .env
# Edit .env with your MySQL connection details
# Run tests
pytest

Considerações de Segurança

Validação de Identificadores: Nomes de tabelas e bancos de dados passados para get_schema_info e get_table_sample são validados contra uma lista de permissões estrita (apenas alfanuméricos, sublinhados e $; um único ponto é permitido como separador de database.table). Outros caracteres especiais são rejeitados para prevenir injeção de SQL.
Acesso Criptografado: Suporte completo a SSL/TLS e Túnel SSH para conexões remotas seguras.
Privacidade de Logs: Senhas e chaves privadas SSH são automaticamente mascaradas nos logs do servidor.
Menor Privilégio: Sempre use um usuário MySQL dedicado com as permissões mínimas necessárias.
O transporte SSE não possui autenticação integrada. O servidor SSE vincula-se a 0.0.0.0 por padrão e aceita conexões sem credenciais. Se você o expor além do localhost, coloque-o atrás de um proxy reverso (nginx, Caddy, Traefik) que aplique autenticação. Exemplo com nginx e Autenticação Básica HTTP:
```
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;
}
```
Defina MCP_SSE_HOST=127.0.0.1 para que o servidor escute apenas no loopback e o proxy seja o único ponto de entrada público. Defina MCP_SSE_ALLOWED_HOSTS para o nome de host público para o qual seu proxy encaminha (por exemplo, MCP_SSE_ALLOWED_HOSTS=myserver.example.com:443).

Consulte SECURITY.md para um guia abrangente sobre como proteger sua implantação.

Melhores Práticas de Segurança

Esta implementação MCP requer acesso ao banco de dados para funcionar. Para segurança:

Crie um usuário MySQL dedicado com permissões mínimas
Nunca use credenciais de root ou contas administrativas
Restrinja o acesso ao banco de dados apenas às operações necessárias
Ative o registro de logs para fins de auditoria
Revisões regulares de segurança do acesso ao banco de dados

Consulte Guia de Configuração de Segurança MySQL para instruções detalhadas sobre:

Criar um usuário MySQL restrito
Definir permissões apropriadas
Monitorar o acesso ao banco de dados
Melhores práticas de segurança

⚠️ IMPORTANTE: Sempre siga o princípio do menor privilégio ao configurar o acesso ao banco de dados.

Licença

Licença MIT — consulte o arquivo LICENSE para obter detalhes.

Contribuição

Faça um fork do repositório
Crie seu branch de recurso (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add some amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request