MySQL Server

Fornece acesso somente leitura a bancos de dados MySQL, permitindo que LLMs inspecionem esquemas e executem consultas.

Documentação

Servidor MCP para MySQL baseado em NodeJS

Demo

Um servidor Model Context Protocol que fornece acesso somente leitura a bancos de dados MySQL. Este servidor permite que LLMs inspecionem esquemas de banco de dados e executem consultas somente leitura.

Instalação

Usando Smithery

A maneira mais fácil de instalar e configurar este servidor MCP é através do Smithery:

# Install the MCP server
npx -y @smithery/cli@latest install @benborla29/mcp-server-mysql --client claude

Durante a configuração, você será solicitado a inserir seus detalhes de conexão MySQL. O Smithery irá automaticamente:

Configurar as variáveis de ambiente corretas
Configurar seu aplicativo LLM para usar o servidor MCP
Testar a conexão com seu banco de dados MySQL
Fornecer ajuda útil para solução de problemas, se necessário

Usando MCP Get

Você também pode instalar este pacote usando MCP Get:

npx @michaellatman/mcp-get@latest install @benborla29/mcp-server-mysql

O MCP Get fornece um registro centralizado de servidores MCP e simplifica o processo de instalação.

Usando NPM/PNPM

Para instalação manual:

# Using npm
npm install -g @benborla29/mcp-server-mysql

# Using pnpm
pnpm add -g @benborla29/mcp-server-mysql

Após a instalação manual, você precisará configurar seu aplicativo LLM para usar o servidor MCP (veja a seção Configuração abaixo).

Componentes

Ferramentas

mysql_query
- Executa consultas SQL somente leitura no banco de dados conectado
- Entrada: sql (string): a consulta SQL a ser executada
- Todas as consultas são executadas dentro de uma transação SOMENTE LEITURA
- Suporta declarações preparadas para manipulação segura de parâmetros
- Timeouts de consulta e paginação de resultados configuráveis
- Estatísticas de execução de consulta integradas

Recursos

O servidor fornece informações abrangentes do banco de dados:

Esquemas de Tabelas
- Informações de esquema JSON para cada tabela
- Nomes de colunas e tipos de dados
- Informações de índices e restrições
- Relacionamentos de chaves estrangeiras
- Estatísticas e métricas de tabelas
- Descobertos automaticamente a partir dos metadados do banco de dados

Recursos de Segurança

Prevenção de injeção SQL através de declarações preparadas
Capacidades de listagem de consultas (whitelist/blacklist)
Limitação de taxa para execução de consultas
Análise de complexidade de consultas
Criptografia de conexão configurável
Aplicação de transações somente leitura

Otimizações de Performance

Pool de conexões otimizado
Cache de resultados de consultas
Streaming de grandes conjuntos de resultados
Análise do plano de execução de consultas
Timeouts de consulta configuráveis

Monitoramento e Depuração

Registro abrangente de consultas
Coleta de métricas de performance
Rastreamento e relatórios de erros
Endpoints de verificação de saúde
Estatísticas de execução de consultas

Configuração

Configuração Automática com Smithery

Se você instalou usando o Smithery, sua configuração já está pronta. Você pode visualizá-la ou modificá-la com:

smithery configure @benborla29/mcp-server-mysql

Configuração Manual para o Claude Desktop App

Para configurar manualmente o servidor MCP para o Claude Desktop App, adicione o seguinte ao seu arquivo claude_desktop_config.json (normalmente localizado no diretório do usuário):

{
  "mcpServers": {
    "mcp_server_mysql": {
      "command": "npx",
      "args": [
        "-y",
        "@benborla29/mcp-server-mysql"
      ],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASS": "",
        "MYSQL_DB": "db_name"
      }
    }
  }
}

Substitua db_name pelo nome do seu banco de dados ou deixe em branco para acessar todos os bancos de dados.

Opções Avançadas de Configuração

Para mais controle sobre o comportamento do servidor MCP, você pode usar estas opções avançadas de configuração:

{
  "mcpServers": {
    "mcp_server_mysql": {
      "command": "/path/to/npx/binary/npx",
      "args": [
        "-y",
        "@benborla29/mcp-server-mysql"
      ],
      "env": {
        // Basic connection settings
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASS": "",
        "MYSQL_DB": "db_name",
        "PATH": "/path/to/node/bin:/usr/bin:/bin",
        
        // Performance settings
        "MYSQL_POOL_SIZE": "10",
        "MYSQL_QUERY_TIMEOUT": "30000",
        "MYSQL_CACHE_TTL": "60000",
        
        // Security settings
        "MYSQL_RATE_LIMIT": "100",
        "MYSQL_MAX_QUERY_COMPLEXITY": "1000",
        "MYSQL_SSL": "true",
        
        // Monitoring settings
        "MYSQL_ENABLE_LOGGING": "true",
        "MYSQL_LOG_LEVEL": "info",
        "MYSQL_METRICS_ENABLED": "true"
      }
    }
  }
}

Variáveis de Ambiente

Conexão Básica

MYSQL_HOST: host do servidor MySQL (padrão: "127.0.0.1")
MYSQL_PORT: porta do servidor MySQL (padrão: "3306")
MYSQL_USER: nome de usuário MySQL (padrão: "root")
MYSQL_PASS: senha MySQL
MYSQL_DB: nome do banco de dados de destino

Configuração de Performance

MYSQL_POOL_SIZE: tamanho do pool de conexões (padrão: "10")
MYSQL_QUERY_TIMEOUT: timeout de consulta em milissegundos (padrão: "30000")
MYSQL_CACHE_TTL: tempo de vida do cache em milissegundos (padrão: "60000")

Configuração de Segurança

MYSQL_RATE_LIMIT: máximo de consultas por minuto (padrão: "100")
MYSQL_MAX_QUERY_COMPLEXITY: pontuação máxima de complexidade de consulta (padrão: "1000")
MYSQL_SSL: habilitar criptografia SSL/TLS (padrão: "false")

Configuração de Monitoramento

MYSQL_ENABLE_LOGGING: habilitar registro de consultas (padrão: "false")
MYSQL_LOG_LEVEL: nível de registro (padrão: "info")
MYSQL_METRICS_ENABLED: habilitar métricas de performance (padrão: "false")

Testes

Configuração do Banco de Dados

Antes de executar os testes, você precisa configurar o banco de dados de teste e populá-lo com dados de teste:

Criar Banco de Dados e Usuário de Teste

-- Connect as root and create test database
CREATE DATABASE IF NOT EXISTS mcp_test;

-- Create test user with appropriate permissions
CREATE USER IF NOT EXISTS 'mcp_test'@'localhost' IDENTIFIED BY 'mcp_test_password';
GRANT ALL PRIVILEGES ON mcp_test.* TO 'mcp_test'@'localhost';
FLUSH PRIVILEGES;

Executar Script de Configuração do Banco de Dados
```
# Run the database setup script
pnpm run setup:test:db
```
Isso criará as tabelas necessárias e os dados de exemplo. O script está localizado em scripts/setup-test-db.ts

Configurar o Ambiente de Teste Crie um arquivo .env.test na raiz do projeto:

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=mcp_test
MYSQL_PASS=mcp_test_password
MYSQL_DB=mcp_test

Atualizar Scripts do package.json Adicione estes scripts ao seu package.json:

{
  "scripts": {
    "setup:test:db": "ts-node scripts/setup-test-db.ts",
    "pretest": "pnpm run setup:test:db",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage"
  }
}

Executando Testes

O projeto inclui um conjunto abrangente de testes para garantir funcionalidade e confiabilidade:

# First-time setup
pnpm run setup:test:db

# Run all tests
pnpm test

Solução de Problemas

Usando Smithery para Solução de Problemas

Se você instalou com o Smithery, pode usar seus diagnósticos integrados:

# Check the status of your MCP server
smithery status @benborla29/mcp-server-mysql

# Run diagnostics
smithery diagnose @benborla29/mcp-server-mysql

# View logs
smithery logs @benborla29/mcp-server-mysql

Usando MCP Get para Solução de Problemas

Se você instalou com o MCP Get:

# Check the status
mcp-get status @benborla29/mcp-server-mysql

# View logs
mcp-get logs @benborla29/mcp-server-mysql

Problemas Comuns

Problemas de Conexão
- Verifique se o servidor MySQL está em execução e acessível
- Verifique as credenciais e permissões
- Certifique-se de que a configuração SSL/TLS está correta, se habilitada
- Tente conectar com um cliente MySQL para confirmar o acesso
Problemas de Performance
- Ajuste o tamanho do pool de conexões
- Configure os valores de timeout de consulta
- Habilite o cache de consultas, se necessário
- Verifique as configurações de complexidade de consulta
- Monitore o uso de recursos do servidor
Restrições de Segurança
- Revise a configuração de limitação de taxa
- Verifique as configurações de whitelist/blacklist de consultas
- Verifique as configurações de SSL/TLS
- Certifique-se de que o usuário tem as permissões MySQL apropriadas
Resolução de Caminhos Se você encontrar o erro "Could not connect to MCP server mcp-server-mysql", defina explicitamente o caminho de todos os binários necessários:

{
  "env": {
    "PATH": "/path/to/node/bin:/usr/bin:/bin"
  }
}

Problemas de Autenticação
- Para MySQL 8.0+, certifique-se de que o servidor suporta o plugin de autenticação caching_sha2_password
- Verifique se seu usuário MySQL está configurado com o método de autenticação correto
- Tente criar um usuário com autenticação legada, se necessário:
```
CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';
```

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request para https://github.com/benborla/mcp-server-mysql

Configuração de Desenvolvimento

Clone o repositório
Instale as dependências: pnpm install
Compile o projeto: pnpm run build
Execute os testes: pnpm test

Roteiro do Projeto

Estamos trabalhando ativamente para melhorar este servidor MCP. Consulte nosso CHANGELOG.md para detalhes sobre os recursos planejados, incluindo:

Capacidades aprimoradas de consulta com declarações preparadas
Recursos avançados de segurança
Otimizações de performance
Monitoramento abrangente
Informações expandidas de esquema

Se você gostaria de contribuir para alguma dessas áreas, verifique as issues no GitHub ou abra uma nova para discutir suas ideias.

Enviando Alterações

Faça um fork do repositório
Crie um branch de recurso: git checkout -b feature/your-feature-name
Faça commit das suas alterações: git commit -am 'Add some feature'
Envie para o branch: git push origin feature/your-feature-name
Envie um pull request

Licença

Este servidor MCP é licenciado sob a Licença MIT. Consulte o arquivo LICENSE para mais detalhes.