MySQL MCP Server

Um servidor MCP para acessar e gerenciar bancos de dados MySQL.

GitHub
2
Experimente este MCPPatrocinado

Documentação

Servidor MCP MySQL

Um servidor Model Context Protocol (MCP) que fornece acesso a banco de dados MySQL por meio de ferramentas padronizadas.

Recursos

  • Execução de Consultas: Execute consultas SQL arbitrárias
  • Inspeção de Esquema: Visualize esquemas de tabelas
  • Listagem de Tabelas: Liste todas as tabelas no banco de dados
  • Análise de Consultas: Analise planos de execução de consultas com sugestões de otimização

Requisitos

  • Go 1.21+ (desenvolvido com Go 1.23.6)
  • MySQL 5.7+ ou MySQL 8.0+
  • Make (para comandos de build)

Instalação

Opção 1: Baixar Binário Pré-compilado (Recomendado)

Baixe a versão mais recente para sua plataforma:

Linux (amd64):

curl -L https://github.com/koh/mysql-mcp-server/releases/latest/download/mysql-mcp-server-linux-amd64.tar.gz | tar xz
chmod +x mysql-mcp-server
sudo mv mysql-mcp-server /usr/local/bin/

macOS (Apple Silicon):

curl -L https://github.com/koh/mysql-mcp-server/releases/latest/download/mysql-mcp-server-darwin-arm64.tar.gz | tar xz
chmod +x mysql-mcp-server
mv mysql-mcp-server /usr/local/bin/

macOS (Intel):

curl -L https://github.com/koh/mysql-mcp-server/releases/latest/download/mysql-mcp-server-darwin-amd64.tar.gz | tar xz
chmod +x mysql-mcp-server
mv mysql-mcp-server /usr/local/bin/

Windows:

# Download from https://github.com/koh/mysql-mcp-server/releases/latest
# Extract mysql-mcp-server-windows-amd64.zip
# Add to PATH or move mysql-mcp-server.exe to a directory in PATH

Opção 2: Compilar a partir do Código Fonte

  1. Clone o repositório:
git clone https://github.com/koh/mysql-mcp-server.git
cd mysql-mcp-server
  1. Instale as dependências e compile:
make build
# Or use make setup for full development setup

Verificar Instalação

Após a instalação, verifique se o servidor está acessível:

mysql-mcp-server --version

Configuração

O servidor usa variáveis de ambiente para a configuração da conexão MySQL:

  • MYSQL_HOST: Host do servidor MySQL (padrão: localhost)
  • MYSQL_PORT: Porta do servidor MySQL (padrão: 3306)
  • MYSQL_USER: Nome de usuário do MySQL
  • MYSQL_PASSWORD: Senha do MySQL
  • MYSQL_DATABASE: Nome do banco de dados para conectar

Você pode copiar .env.example para .env e modificá-lo com suas credenciais:

cp .env.example .env

Uso

Com Claude Desktop

Adicione o servidor ao seu arquivo de configuração do Claude Desktop:

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

{
  "mcpServers": {
    "mysql": {
      "command": "mysql-mcp-server",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Uso Direto

Execute o servidor diretamente:

export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USER=root
export MYSQL_PASSWORD=password
export MYSQL_DATABASE=testdb
./mysql-mcp-server

Ferramentas Disponíveis

query

Execute consultas SELECT para recuperar dados do banco de dados MySQL. Esta ferramenta é restrita apenas a instruções SELECT por segurança. Use a ferramenta execute para operações de modificação de dados.

Parâmetros:

  • query (obrigatório): Apenas instrução SELECT
  • format (opcional): Formato de saída - json, table, csv ou markdown (padrão: table)

Exemplo:

{
  "name": "query",
  "arguments": {
    "query": "SELECT * FROM users WHERE status = 'active' LIMIT 10",
    "format": "csv"
  }
}

execute

Execute consultas INSERT, UPDATE, DELETE com verificações de segurança. Esta ferramenta implementa um processo de execução em duas etapas por segurança:

  1. Primeiro execute com dry_run=true para visualizar as linhas afetadas
  2. Depois execute com dry_run=false e o token de confirmação para executar

Parâmetros:

  • sql (obrigatório): Instrução INSERT, UPDATE ou DELETE
  • dry_run (opcional): Se verdadeiro, mostra as linhas afetadas sem executar (padrão: verdadeiro)
  • confirm_token (opcional): Token da resposta do dry-run, obrigatório quando dry_run=falso

Exemplo - Etapa 1 (Dry Run):

{
  "name": "execute",
  "arguments": {
    "sql": "UPDATE users SET status = 'inactive' WHERE last_login < '2024-01-01'",
    "dry_run": true
  }
}

Resposta:

{
  "content": [
    {"type": "text", "text": "DRY RUN - Operation: UPDATE"},
    {"type": "text", "text": "This operation will affect 42 rows"},
    {"type": "text", "text": "To execute this query, run again with dry_run=false and the confirmation token below:"},
    {"type": "text", "text": "confirm_token: abc123def456"}
  ],
  "affected_rows": 42,
  "operation": "UPDATE",
  "confirm_token": "abc123def456"
}

Exemplo - Etapa 2 (Executar):

{
  "name": "execute",
  "arguments": {
    "sql": "UPDATE users SET status = 'inactive' WHERE last_login < '2024-01-01'",
    "dry_run": false,
    "confirm_token": "abc123def456"
  }
}

schema

Obtenha o esquema de uma tabela MySQL.

Parâmetros:

  • table (obrigatório): O nome da tabela

Exemplo:

{
  "name": "schema",
  "arguments": {
    "table": "users"
  }
}

tables

Liste todas as tabelas no banco de dados.

Exemplo:

{
  "name": "tables",
  "arguments": {}
}

explain

Analise o plano de execução de uma consulta MySQL para entender o desempenho. Suporta EXPLAIN e EXPLAIN ANALYZE.

Parâmetros:

  • query (obrigatório): A consulta SQL a ser analisada
  • analyze (opcional): Se verdadeiro, executa EXPLAIN ANALYZE para obter estatísticas reais de execução (padrão: falso)

Exemplo - EXPLAIN básico:

{
  "name": "explain",
  "arguments": {
    "query": "SELECT * FROM users WHERE email = 'test@example.com'"
  }
}

Exemplo - EXPLAIN ANALYZE:

{
  "name": "explain",
  "arguments": {
    "query": "SELECT * FROM users WHERE age > 25",
    "analyze": true
  }
}

Nota: EXPLAIN ANALYZE realmente executa a consulta para coletar estatísticas reais de execução, incluindo contagens reais de linhas e informações de tempo. Use com cautela em consultas que modificam dados ou demoram muito para executar.

Integração com Ferramentas de IA

Integração com VSCode

Opção 1: Usando Extensões de Cliente MCP

Configure no settings.json do VSCode:

{
  "mcp.servers": {
    "mysql": {
      "command": "/path/to/mysql-mcp-server",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "password",
        "MYSQL_DATABASE": "mydb"
      }
    }
  }
}

Opção 2: Extensão Personalizada do VSCode

Crie uma extensão personalizada que inicie o servidor MCP. Consulte INTEGRATION.md para detalhes de implementação.

Integração com Cursor

O Cursor suporta servidores MCP por meio de sua configuração:

  1. Abra as Configurações do Cursor
  2. Navegue até "AI" → "Model Context Protocol"
  3. Adicione a configuração do servidor:
{
  "mysql": {
    "command": "/path/to/mysql-mcp-server",
    "env": {
      "MYSQL_HOST": "localhost",
      "MYSQL_USER": "root",
      "MYSQL_PASSWORD": "password",
      "MYSQL_DATABASE": "mydb"
    }
  }
}

Integração com GitHub Copilot

O GitHub Copilot não suporta diretamente servidores MCP, mas você pode criar uma ponte por meio de extensões do VSCode. Consulte INTEGRATION.md para implementação detalhada.

Padrão de Integração Genérico

Para qualquer ferramenta que suporte comunicação por subprocesso:

const { spawn } = require('child_process');

class MCPClient {
    constructor(serverPath, env) {
        this.server = spawn(serverPath, [], { env });
        // ... handle communication
    }

    async callTool(name, arguments) {
        return this.request('tools/call', { name, arguments });
    }
}

// Usage
const client = new MCPClient('/path/to/mysql-mcp-server', {
    MYSQL_HOST: 'localhost',
    MYSQL_USER: 'root',
    MYSQL_PASSWORD: 'password',
    MYSQL_DATABASE: 'mydb'
});

Para exemplos completos de integração e solução de problemas, consulte INTEGRATION.md.

Testes

Para instruções detalhadas de teste, consulte TESTING.md.

Início rápido:

# Setup and run interactive test client
make setup
make test-client

Desenvolvimento

Execute os testes:

make test

Execute o servidor:

make run

Considerações de Segurança

  • A ferramenta query é restrita apenas a instruções SELECT para evitar modificação acidental de dados
  • A ferramenta execute requer um processo de confirmação em duas etapas para todas as operações de modificação de dados
  • Nunca exponha este servidor a clientes não confiáveis
  • Use permissões de usuário MySQL apropriadas
  • Considere usar usuários de banco de dados somente leitura quando possível
  • O recurso de dry-run permite visualizar o impacto das operações UPDATE/DELETE antes da execução
  • Os tokens de confirmação expiram após 5 minutos por segurança
  • Mantenha suas credenciais de banco de dados seguras

Licença

MIT