MCP 服务器

MCP MySQL Server

A reusable MCP server for MySQL that enables native integration with Cursor IDE, allowing SQL queries, table inspection, and database exploration.

README

🔌 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

Nunca commite o arquivo .env
- Ele está no .gitignore por segurança

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;

Conexão apenas local
- O servidor só aceita conexões de localhost
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:

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

Cursor não encontra o servidor

Solução:

Verifique o caminho absoluto no args
Reinicie o Cursor completamente
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",
        ...
      }
    }
  }
}