mcp-mysql-client

Servidor MCP para um banco de dados MySQL — inspeção de esquema, consultas somente leitura e gravações protegidas de um banco de dados para agentes de IA.

GitHubExperimente este MCPPatrocinado

Documentação

MySQL MCP

MySQL MCP conecta um aplicativo de IA a um único banco de dados MySQL ou MariaDB: visualizar a estrutura, fazer perguntas aos dados em linguagem natural, entender uma consulta lenta — e, se você mesmo permitir, alterar dados.

O servidor está vinculado a um único banco: ele é definido pela configuração, e nenhuma ferramenta pode acessar outro. Por padrão, apenas leitura está disponível.

6 ferramentas. Conexão e permissões, lista de tabelas, estrutura da tabela, consulta de leitura, plano de consulta, consulta de escrita.
O tipo de consulta é determinado pelo servidor. O SQL é analisado antes da conexão: DELETE em uma ferramenta de leitura será rejeitado, mesmo que as permissões de escrita estejam habilitadas.
Leitura não pode escrever. Consultas de leitura são executadas dentro de START TRANSACTION READ ONLY — a escrita será rejeitada pelo próprio MySQL, mesmo que alguém engane a análise do SQL.
A resposta não estourará o contexto. As linhas são lidas em fluxo e interrompidas no limite, não baixadas inteiras; a resposta inclui um indicador honesto truncated.
Permissões apenas externamente. INSERT, UPDATE e DELETE são habilitados por variáveis de ambiente e exigem reinicialização — não podem ser obtidos pelo diálogo. DDL está sempre indisponível.

Comece com uma consulta que apenas lê dados:

Mostre a estrutura do banco e conte quantos registros foram criados na última semana.

Início rápido

Claude Code:

claude mcp add mysql-myapp \
  -e MYSQL_HOST=db.example.com \
  -e MYSQL_USER=myapp_ro \
  -e MYSQL_PASS='пароль' \
  -e MYSQL_DB=myapp \
  -e MYSQL_SSL=true \
  -- npx -y mcp-mysql-client

Ou em .mcp.json / claude_desktop_config.json:

{
  "mcpServers": {
    "mysql-myapp": {
      "command": "npx",
      "args": ["-y", "mcp-mysql-client"],
      "env": {
        "MYSQL_HOST": "db.example.com",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "myapp_ro",
        "MYSQL_PASS": "пароль",
        "MYSQL_DB": "myapp",
        "MYSQL_SSL": "true"
      }
    }
  }
}

Um servidor — um banco. Precisa de vários bancos: adicione várias entradas com suas próprias credenciais; assim as permissões permanecem isoladas, e o servidor conectado ao banco de teste fisicamente não vê o banco de produção.

O que você pode pedir

Consulta	O que o servidor faz
"O que existe neste banco?"	`list_tables` — tabelas, tamanhos, estimativas de contagem de linhas
"Como é a estrutura da tabela orders?"	`describe_table` — colunas, índices, chaves estrangeiras em ambas as direções
"Quantos pedidos em julho e por qual valor?"	`query` — SELECT com agregação
"Por que esta consulta está lenta?"	`explain` — plano, índices, estimativa de linhas
"Com qual usuário estou conectado e o que posso fazer?"	`server_info` — banco, usuário, GRANT, limites do servidor
"Marque o status dos pedidos cancelados"	`execute` — somente com `ALLOW_UPDATE_OPERATION=true`

O que pode mudar

Por padrão — nada: o servidor inicia em modo somente leitura. A escrita é habilitada por operação:

"ALLOW_INSERT_OPERATION": "true",
"ALLOW_UPDATE_OPERATION": "true",
"ALLOW_DELETE_OPERATION": "false"

O que permanece impossível:

DDL — CREATE, ALTER, DROP, TRUNCATE, RENAME — em nenhuma configuração.
Troca de banco, SET, CALL, PREPARE, LOAD DATA, bloqueios, GRANT e outras operações que alteram o significado da próxima consulta ou executam texto não verificado.
SELECT ... INTO OUTFILE — gravação de arquivo no servidor do banco.
UPDATE e DELETE sem WHERE — exigem confirmação explícita allow_full_table=true na chamada.
Várias instruções em uma única chamada — exatamente uma é executada.

As permissões do MySQL são uma restrição adicional além disso. A permissão ALLOW_UPDATE_OPERATION não adiciona nada a um usuário sem GRANT UPDATE. Boa prática: um usuário separado com permissões mínimas, não root.

Variáveis de ambiente

Variável	Padrão	Finalidade
`MYSQL_HOST`	`127.0.0.1`	Host do servidor
`MYSQL_PORT`	`3306`	Porta
`MYSQL_SOCKET_PATH`	—	Socket Unix em vez de host/porta
`MYSQL_USER`	—	Usuário (obrigatório)
`MYSQL_PASS`	—	Senha (sinônimo de `MYSQL_PASSWORD`)
`MYSQL_PASS_FILE`	—	Ler a senha de um arquivo em vez de uma variável
`MYSQL_DB`	—	Banco de dados (obrigatório, sinônimo de `MYSQL_DATABASE`)
`MYSQL_SSL`	`false`	Exigir TLS
`MYSQL_SSL_CA`	—	Caminho para o certificado raiz; por si só habilita TLS
`MYSQL_SSL_REJECT_UNAUTHORIZED`	`true`	Verificar o certificado do servidor
`ALLOW_INSERT_OPERATION`	`false`	Permitir INSERT
`ALLOW_UPDATE_OPERATION`	`false`	Permitir UPDATE
`ALLOW_DELETE_OPERATION`	`false`	Permitir DELETE
`MYSQL_MAX_ROWS`	`1000`	Limite de linhas em uma única resposta
`MYSQL_TIMEOUT_MS`	`30000`	Timeout da consulta
`MYSQL_CONNECT_TIMEOUT_MS`	`10000`	Timeout da conexão
`MYSQL_POOL_SIZE`	`3`	Conexões no pool
`MYSQL_MAX_RETRIES`	`2`	Tentativas em caso de queda de conexão e deadlocks
`MYSQL_READ_ONLY_TX`	`true`	Executar leitura em transação somente leitura
`ASKADS_TELEMETRY`	—	`0` desativa estatísticas anônimas de execução

A senha na configuração do cliente MCP fica em texto puro. MYSQL_PASS_FILE permite mantê-la em um arquivo com as permissões adequadas.

Migração do `@benborla29/mcp-server-mysql`

Os nomes das variáveis coincidem, então basta substituir o pacote no comando de inicialização:

-  "args": ["-y", "@benborla29/mcp-server-mysql"]
+  "args": ["-y", "mcp-mysql-client"]

O que mudará no comportamento:

MYSQL_DB é obrigatório — o servidor está sempre vinculado a um único banco;
as respostas são limitadas a MYSQL_MAX_ROWS e marcadas com truncated;
DDL está indisponível mesmo com permissões de escrita habilitadas;
UPDATE/DELETE sem WHERE exigem confirmação na chamada;
o conjunto de ferramentas é diferente: query, execute, explain, list_tables, describe_table, server_info.

Diagnóstico

Primeiro — server_info: ele mostrará a que o servidor está conectado, quais permissões o usuário MySQL possui e quais limites estão habilitados.

Sintoma	Causa
`errno 1045`	`MYSQL_USER` / `MYSQL_PASS` incorretos
`errno 1044`	O usuário existe, mas não tem permissão no banco
`errno 1142`	Falta `GRANT` para a operação ou tabela — `ALLOW_*` não ajudará aqui
`errno 3159`	O servidor exige TLS: `MYSQL_SSL=true`
`ECONNREFUSED` / `ETIMEDOUT`	Host, porta, firewall ou VPN não ativada
`ER_NOT_SUPPORTED_AUTH_MODE`	TLS necessário para `caching_sha2_password`
O servidor não conecta	O erro de configuração aparece diretamente no diálogo: o servidor inicia mesmo sem credenciais e explica o que está faltando

Documentação técnica

Ferramentas — parâmetros e respostas
Desenvolvimento — build, testes, verificação ao vivo
Publicação — release no npm e no registro MCP
CLAUDE.md — estrutura do repositório para agentes de IA

Licença

MIT