efeabio/mcp-mysql-server

🚀 MCP MySQL Server

Um servidor MCP (Model Context Protocol) robusto e profissional para interação com bancos MySQL através de agentes de IA. Este projeto demonstra implementação avançada de protocolos MCP com gerenciamento inteligente de conexões e ferramentas especializadas para análise de bancos de dados.

✨ Características Principais

• 🔐 Gerenciamento Inteligente de Conexões - Configuração dinâmica via tools MCP
• 🛡️ Segurança Robusta - Apenas operações SELECT permitidas, validação de entrada com Zod
• 🔄 Múltiplos Transportes - Suporte a stdio e SSE para diferentes cenários de uso
• 📊 Ferramentas Especializadas - Análise de schema, foreign keys e estrutura de tabelas
• 🚀 Configuração Automática - Descoberta inteligente de configurações MySQL
• 💡 Fallback Interativo - Solicita configuração quando necessário

🛠️ Ferramentas Disponíveis

🔧 Configuração de Conexão

• mysql_configure_connection - Configuração dinâmica de conexão MySQL
• mysql_auto_configure_connection - Descoberta automática de configuração
• mysql_get_connection_status - Status atual da conexão
• mysql_check_connection - Teste de conectividade

📊 Operações no Banco

• mysql_list_tables - Listagem de todas as tabelas
• mysql_get_table_info - Estrutura detalhada de tabelas
• mysql_execute_query - Execução de queries SELECT
• mysql_analyze_schema - Análise completa do schema
• mysql_list_foreign_keys - Mapeamento de relacionamentos

🚀 Instalação e Configuração

1. Clone e Instale

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

2. Configure o Cursor

Adicione a seguinte configuração no seu arquivo ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mysql": {
      "command": "/caminho/para/seu/projeto/start-mcp.sh"
    }
  }
}

⚠️ Importante: Substitua /caminho/para/seu/projeto/ pelo caminho real onde você clonou o repositório.

3. Configure o start-mcp.sh

Edite o arquivo start-mcp.sh e altere o caminho para corresponder à sua instalação:

#!/bin/bash
node /caminho/para/seu/projeto/dist/index.js

4. Configuração da Conexão MySQL

O projeto oferece 3 formas de configurar a conexão MySQL:

🔧 Configuração Manual via Tool (Recomendado)

Use a tool mysql_configure_connection para configurar dinamicamente:

await mysql_configure_connection({
  host: "localhost",
  port: 3306,
  user: "root",
  password: "sua_senha",
  database: "seu_banco"
});

📁 Configuração via Arquivo

Crie um arquivo config.json na raiz do projeto:

{
  "mysql": {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "sua_senha",
    "database": "seu_banco"
  }
}

🔍 Descoberta Automática

Use a tool mysql_auto_configure_connection para tentar descobrir configuração automaticamente.

🎯 Casos de Uso

🔍 Análise de Banco de Dados

• Auditoria de Schema - Mapeamento completo de estruturas
• Análise de Relacionamentos - Identificação de foreign keys
• Documentação Automática - Geração de documentação de banco

🤖 Integração com Agentes de IA

• Consultas Inteligentes - Execução de queries via linguagem natural
• Exploração Interativa - Descoberta de dados sem conhecimento prévio
• Análise Automática - Insights sobre estrutura e relacionamentos

🚀 Desenvolvimento e DevOps

• Migração de Dados - Análise de estrutura antes de migrações
• Debugging - Investigação de problemas de banco
• Monitoramento - Verificação de integridade de dados

🔒 Segurança e Boas Práticas

• ✅ Operações Somente Leitura - Apenas SELECT é permitido
• ✅ Validação de Entrada - Schema validation com Zod
• ✅ Teste de Conexão - Verificação antes de aceitar configurações
• ✅ Configuração via Tools - Interface segura para configuração
• ✅ Isolamento de Conexões - Gerenciamento seguro de múltiplas conexões

🚀 Execução

# Modo stdio (padrão para MCP)
./start-mcp.sh

# Modo SSE para desenvolvimento
node dist/index.js sse

📚 Exemplos de Uso

Configuração Inicial

// Configure conexão dinamicamente
await mysql_configure_connection({
  host: "localhost",
  port: 3306,
  user: "root",
  password: "sua_senha",
  database: "test"
});

// Verifique se funcionou
await mysql_check_connection();

// Explore o banco
await mysql_list_tables();

Análise de Schema

// Análise completa
await mysql_analyze_schema();

// Relacionamentos
await mysql_list_foreign_keys();

// Estrutura específica
await mysql_get_table_info("users");

Consultas Personalizadas

// Execute queries SELECT
await mysql_execute_query("SELECT COUNT(*) as total FROM users");

// Análise de dados
await mysql_execute_query("SELECT table_name, table_rows FROM information_schema.tables");

🏗️ Arquitetura

O projeto utiliza uma arquitetura modular com:

• MCP SDK - Implementação do protocolo Model Context Protocol
• MySQL2 - Driver nativo e performático para MySQL
• TypeScript - Tipagem estática e desenvolvimento robusto
• Zod - Validação de schemas e entrada de dados
• Express - Suporte opcional para transporte SSE

🔧 Desenvolvimento

# Build do projeto
npm run build

# Execução em modo desenvolvimento
npm start

# Execução com SSE
npm start sse

📄 Licença

MIT License - veja o arquivo LICENSE para detalhes.

🤝 Contribuição

Contribuições são bem-vindas! Este projeto demonstra implementação profissional de protocolos MCP e serve como referência para desenvolvimento de servidores MCP robustos.

Desenvolvido com ❤️ para demonstrar expertise em protocolos MCP, integração com MySQL e desenvolvimento de ferramentas para agentes de IA.