🔌 MCP MySQL Server

Servidor MCP (Model Context Protocol) para MySQL - Módulo reutilizável que permite integração nativa entre Cursor IDE e qualquer banco de dados MySQL.

---

📋 O que é isso?

Este é um servidor MCP que permite que o Cursor (e outras ferramentas que suportam MCP) executem queries SQL diretamente no seu banco MySQL local, facilitando:

• ✅ Análise de estrutura de tabelas
• ✅ Consultas de dados em tempo real
• ✅ Geração de código baseado no schema
• ✅ Debugging de queries
• ✅ Inspeção de relacionamentos

---

🚀 Instalação Rápida

1. Instalar Dependências

cd mcp-mysql-server
npm install

2. Configurar Credenciais

# Windows
copy env.example .env

# Linux/Mac
cp env.example .env

Edite o arquivo .env com suas credenciais:

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=sua_senha_aqui
MYSQL_DATABASE=food

3. Testar Conexão

npm start

Se aparecer [MCP MySQL] Servidor MCP iniciado com sucesso, está funcionando! ✅

---

⚙️ Configuração no Cursor

Windows

Edite o arquivo de configuração do Cursor:

Caminho: %APPDATA%\Cursor\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json

Ou acesse via Cursor: Settings → Extensions → MCP Servers

Adicione:

{
  "mcpServers": {
    "mysql-food": {
      "command": "node",
      "args": ["G:/IA/Estudos/mcp-mysql-server/src/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "SuaSenhaAqui",
        "MYSQL_DATABASE": "food"
      }
    }
  }
}

Linux/Mac

Caminho: ~/.config/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "mysql-food": {
      "command": "node",
      "args": ["/caminho/completo/mcp-mysql-server/src/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "SuaSenhaAqui",
        "MYSQL_DATABASE": "food"
      }
    }
  }
}

4. Reiniciar Cursor

Feche e abra o Cursor completamente para carregar o servidor MCP.

---

🛠️ Ferramentas Disponíveis

1. mysql_execute_query

Executa qualquer query SQL.

Exemplo:

SELECT * FROM combos WHERE COD = 9;

Parâmetros:

• query (string): Query SQL
• params (array, opcional): Parâmetros para prepared statements

Uso com prepared statements:

SELECT * FROM users WHERE id = ? AND status = ?
Params: [1, "active"]

---

2. mysql_list_tables

Lista todas as tabelas do banco de dados.

Retorna:

{
  "success": true,
  "database": "food",
  "tableCount": 15,
  "tables": ["combos", "detcombos", "produtos", ...]
}

---

3. mysql_describe_table

Mostra a estrutura completa de uma tabela.

Parâmetros:

• table_name (string): Nome da tabela

Exemplo:

table_name: "combos"

Retorna:

{
  "success": true,
  "table": "combos",
  "columns": [
    {
      "Field": "COD",
      "Type": "int",
      "Null": "NO",
      "Key": "PRI",
      "Default": null,
      "Extra": "auto_increment"
    },
    ...
  ]
}

---

4. mysql_show_databases

Lista todos os databases disponíveis no servidor.

Retorna:

{
  "success": true,
  "databases": ["food", "mysql", "information_schema", ...]
}

---

5. mysql_table_info

Retorna informações completas: colunas, índices e contagem de registros.

Parâmetros:

• table_name (string): Nome da tabela

Retorna:

{
  "success": true,
  "table": "combos",
  "rowCount": 25,
  "columns": [...],
  "indexes": [...]
}

---

🎯 Exemplos de Uso

No Chat do Cursor

Depois de configurado, você pode pedir ao assistente:

"Liste todas as tabelas do banco food"
"Mostre a estrutura da tabela combos"
"Execute: SELECT * FROM detcombos WHERE CODCOMBO = 9"
"Quantos registros tem na tabela movimento?"

O assistente vai usar automaticamente as ferramentas MCP!

---

🔒 Segurança

✅ Boas Práticas

1. Nunca commite o arquivo .env

   • Ele está no .gitignore por segurança

2. Use usuário com permissões limitadas

   CREATE USER 'cursor_readonly'@'localhost' IDENTIFIED BY 'senha_segura';
   GRANT SELECT ON food.* TO 'cursor_readonly'@'localhost';
   FLUSH PRIVILEGES;
   

3. Conexão apenas local

   • O servidor só aceita conexões de localhost

4. Prepared Statements

   • Use sempre parâmetros em vez de concatenar strings

---

🐛 Troubleshooting

Erro: "MYSQL_DATABASE não está configurado"

Solução: Crie o arquivo .env a partir do env.example

Erro: "Access denied for user"

Solução: Verifique usuário e senha no .env

Erro: "connect ECONNREFUSED"

Solução:

1. Verifique se o MySQL está rodando
2. Confirme a porta (padrão: 3306)

Cursor não encontra o servidor

Solução:

1. Verifique o caminho absoluto no args
2. Reinicie o Cursor completamente
3. Verifique logs em: View → Output → MCP

Teste manual da conexão

# Testar se o MySQL está respondendo
mysql -u root -p -h localhost -P 3306

# Testar o servidor MCP
cd mcp-mysql-server
node src/index.js

---

📂 Estrutura do Projeto

mcp-mysql-server/
├── src/
│   └── index.js          # Servidor MCP principal
├── package.json          # Dependências e scripts
├── env.example           # Template de configuração
├── .gitignore           # Arquivos ignorados pelo Git
└── README.md            # Este arquivo

---

🔄 Usar em Múltiplos Projetos

Opção 1: Instalar Globalmente

cd mcp-mysql-server
npm link

Depois em qualquer projeto:

npm link @local/mcp-mysql-server

Opção 2: Referenciar Diretamente

No Cursor, aponte para o caminho absoluto do index.js:

"args": ["G:/IA/Estudos/mcp-mysql-server/src/index.js"]

Opção 3: Múltiplos Bancos

Crie múltiplas configurações no Cursor:

{
  "mcpServers": {
    "mysql-food": {
      "command": "node",
      "args": ["G:/IA/Estudos/mcp-mysql-server/src/index.js"],
      "env": {
        "MYSQL_DATABASE": "food",
        ...
      }
    },
    "mysql-ecommerce": {
      "command": "node",
      "args": ["G:/IA/Estudos/mcp-mysql-server/src/index.js"],
      "env": {
        "MYSQL_DATABASE": "ecommerce",
        ...
      }
    }
  }
}

---

📦 Dependências

• @modelcontextprotocol/sdk - SDK oficial do MCP
• mysql2 - Driver MySQL para Node.js (com suporte a Promises)
• dotenv - Gerenciamento de variáveis de ambiente

---

🤝 Contribuindo

Sinta-se livre para melhorar este módulo:

1. Adicionar mais ferramentas
2. Melhorar tratamento de erros
3. Adicionar cache de queries
4. Implementar rate limiting
5. Adicionar logs estruturados

---

📝 Licença

MIT - Use livremente em seus projetos!

---

🎓 Recursos Adicionais

• Documentação MCP
• MySQL2 Docs
• Cursor IDE

---

✨ Autor

Criado para facilitar o desenvolvimento com IA e bancos de dados MySQL.

Versão: 1.0.0
Node.js: >= 18.0.0
Testado em: Node v22.12.0