MySQL Mcp

mysql-mcp

Um servidor Model Context Protocol (MCP) que dá aos agentes de IA acesso direto a bancos de dados MySQL.

O que ele pode fazer

Consulta e Mutação de Dados

• execute_query — Execute instruções SELECT, INSERT, UPDATE ou DELETE com suporte a consultas parametrizadas (placeholders ?)
• execute_transaction — Execute múltiplas instruções como um lote atômico; se qualquer instrução falhar, toda a transação é revertida automaticamente

Gerenciamento de Esquema

• create_table — Criar uma nova tabela
• alter_table — Adicionar/remover colunas, renomear colunas, adicionar índices e mais
• drop_table — Remover uma tabela (requer ALLOW_DESTRUCTIVE_DDL=true)
• show_tables — Listar todas as tabelas em um banco de dados
• describe_table — Mostrar a estrutura de colunas de uma tabela

Gerenciamento de Banco de Dados

• list_databases — Listar todos os bancos de dados do usuário (bancos de dados do sistema excluídos)
• create_database — Criar um novo banco de dados com charset e collation opcionais
• drop_database — Remover um banco de dados (requer ALLOW_DESTRUCTIVE_DDL=true)

Introspecção

• ping — Verificar a saúde da conexão MySQL
• show_columns — Mostrar informações detalhadas das colunas de uma tabela
• get_server_info — Retornar versão do MySQL, conjunto de caracteres e collation (somente leitura)

Suporte a Múltiplos Bancos de Dados

Cada ferramenta aceita um parâmetro database. Você pode consultar diferentes bancos de dados na mesma sessão sem qualquer configuração extra.

---

O que ele não pode fazer

As seguintes operações são permanentemente bloqueadas pelo filtro de segurança e não podem ser contornadas em nenhuma circunstância:

Categoria	Comandos Bloqueados
Configurações do MySQL	SET GLOBAL, SET @@global.*, SET @@SESSION.sql_mode
Gerenciamento de usuários	CREATE USER, DROP USER, ALTER USER, RENAME USER
Gerenciamento de privilégios	GRANT, REVOKE
Comandos do sistema	FLUSH, KILL, SHUTDOWN
Replicação	RESET MASTER/REPLICA, START/STOP SLAVE/REPLICA, CHANGE MASTER
Acesso a arquivos	LOAD DATA INFILE, SELECT INTO OUTFILE/DUMPFILE
Plugins	INSTALL PLUGIN, UNINSTALL PLUGIN

Restrições adicionais:

• Múltiplas instruções separadas por ; em uma única chamada não são permitidas — use execute_transaction em vez disso.
• drop_table e drop_database estão desabilitados por padrão e retornarão um erro a menos que ALLOW_DESTRUCTIVE_DDL=true seja definido.
• Resultados de consulta são limitados a MAX_ROWS linhas (padrão: 1000); adicione uma cláusula LIMIT para tabelas grandes.

---

Instalação

Requisitos: Node.js 20+

git clone https://github.com/turkeryildirim/mysql-mcp
cd mysql-mcp
npm install
npm run build

Copie o arquivo de ambiente de exemplo e preencha suas credenciais:

cp .env.example .env

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=mcp_user
MYSQL_PASSWORD=your_password

# Optional
MYSQL_DATABASE=default_db
MYSQL_POOL_SIZE=10
MAX_ROWS=1000
ALLOW_DESTRUCTIVE_DDL=false

Criando um Usuário MySQL Dedicado (Recomendado)

Crie um usuário MySQL com privilégios mínimos para o servidor MCP:

CREATE USER 'mcp_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, INDEX
  ON *.* TO 'mcp_user'@'localhost';
FLUSH PRIVILEGES;

Não conceda SUPER, FILE, RELOAD ou GRANT OPTION.

---

Integração com Claude Desktop

Abra o arquivo de configuração do Claude Desktop:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Adicione o seguinte bloco sob mcpServers:

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["/absolute/path/to/mysql-mcp/dist/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "",
        "MAX_ROWS": "1000",
        "ALLOW_DESTRUCTIVE_DDL": "false"
      }
    }
  }
}

Reinicie o Claude Desktop. Você deve ver o servidor mysql listado no painel de ferramentas.

---

Integração com Claude CLI

Opção 1: .mcp.json — Escopo do projeto (Recomendado)

Crie um arquivo .mcp.json na raiz do seu projeto:

{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mysql-mcp/dist/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_user",
        "MYSQL_PASSWORD": "your_password",
        "ALLOW_DESTRUCTIVE_DDL": "false"
      }
    }
  }
}

O servidor carrega automaticamente sempre que você executa claude a partir desse diretório.

Opção 2: Configuração global

claude mcp add mysql -- node /absolute/path/to/mysql-mcp/dist/index.js

Para incluir variáveis de ambiente:

claude mcp add mysql \
  -e MYSQL_HOST=localhost \
  -e MYSQL_USER=mcp_user \
  -e MYSQL_PASSWORD=your_password \
  -- node /absolute/path/to/mysql-mcp/dist/index.js

Verifique a configuração:

claude mcp list
claude mcp get mysql

---

Exemplos de Prompts

Uma vez conectado, você pode instruir o agente em linguagem natural:

Show me the structure of the users table in testdb
Fetch the last 10 orders from testdb.orders
Create a products table in testdb with id, name, price, and stock columns
Run the following two INSERTs as a single transaction: ...

---

Desenvolvimento

npm run dev        # Watch mode (rebuilds on change)
npm test           # Unit tests (no MySQL connection required)
npm run build      # Production build → dist/