MySQL MCP

Serviço MCP do Banco de Dados MySQL

Este é um serviço MCP (Model Context Protocol) de banco de dados MySQL projetado especificamente para Cursor, fornecendo consulta de estrutura de tabelas, geração de documentação e funcionalidades de consulta de dados.

Recursos

• Integração dedicada ao Cursor: Serviço de banco de dados projetado para o protocolo MCP do Cursor
• Múltiplos modos de segurança: Suporta três níveis de segurança: somente leitura, escrita limitada e acesso total
• Consulta de estrutura de tabelas: Obtém informações detalhadas da estrutura das tabelas do banco de dados
• Geração de documentação: Gera documentação de estrutura de tabelas nos formatos Markdown, JSON e SQL
• Visão geral do banco de dados: Gera documentação de visão geral para todo o banco de dados
• Execução de consultas SQL: Executa operações SQL em diferentes níveis de acordo com o modo de segurança
• Cache de consultas: Armazena automaticamente em cache os resultados das consultas para melhorar o desempenho

Modos de Segurança

1. Modo Somente Leitura (readonly) - Modo padrão

• Permite apenas operações de consulta como SELECT, SHOW, DESCRIBE, EXPLAIN
• Proíbe todas as operações de escrita e operações perigosas
• Adequado para análise de dados e consultas de relatórios

2. Modo de Escrita Limitada (limited_write)

• Permite operações SELECT, INSERT, UPDATE
• Proíbe operações perigosas como DELETE, DROP, CREATE, ALTER
• Adequado para cenários que exigem entrada de dados, mas precisam proteger a estrutura

3. Modo de Acesso Total (full_access)

• Permite todas as operações SQL
• Use com cautela, habilite apenas em ambientes totalmente confiáveis
• Adequado para administração e manutenção de banco de dados

Instalação e Configuração

1. Instalar dependências localmente

cd mysql-mcp
pip install -r requirements.txt

2. Configurar no Cursor

Encontre a configuração MCP nas configurações do Cursor e adicione o seguinte:

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "python",
      "args": ["F:/path/to/mysql-mcp/main.py"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USERNAME": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database",
        "MYSQL_SECURITY_MODE": "readonly",
        "MYSQL_ALLOWED_SCHEMAS": "*",
        "MYSQL_ENABLE_QUERY_LOG": "false"
      }
    }
  }
}

3. Descrição das variáveis de ambiente

Variáveis de ambiente obrigatórias:

• MYSQL_HOST: Endereço do host do banco de dados
• MYSQL_PORT: Porta do banco de dados
• MYSQL_USERNAME: Nome de usuário do banco de dados
• MYSQL_PASSWORD: Senha do banco de dados
• MYSQL_DATABASE: Nome do banco de dados

Variáveis de ambiente opcionais:

• MYSQL_SECURITY_MODE: Modo de segurança (readonly/limited_write/full_access, padrão: readonly)
• MYSQL_ALLOWED_SCHEMAS: Lista de bancos de dados permitidos, suporta três métodos de configuração:
  • "*": Permite acesso a todos os bancos de dados com permissão (recomendado)
  • "auto": Descobre automaticamente bancos de dados com permissão
  • "db1,db2,db3": Especifica explicitamente a lista de bancos de dados (separados por vírgula)
• MYSQL_CONNECT_TIMEOUT: Tempo limite de conexão (segundos, padrão: 30)
• MYSQL_QUERY_TIMEOUT: Tempo limite de consulta (segundos, padrão: 60)
• MYSQL_MAX_RETRIES: Número máximo de tentativas (padrão: 3)
• MYSQL_ENABLE_QUERY_LOG: Se o log de consultas está habilitado (true/false, padrão: false)
• MYSQL_MAX_RESULT_ROWS: Número máximo de linhas retornadas (padrão: 1000)

Exemplos de Uso

Obter informações de segurança

Digite no Cursor:

@mysql-mcp 获取当前安全配置信息

Visualizar bancos de dados acessíveis

@mysql-mcp 获取所有可访问的数据库

Consultar lista de tabelas

@mysql-mcp 列出 mydb 数据库中的所有表

Visualizar estrutura da tabela

@mysql-mcp 描述 users 表的结构

Executar consulta (modo somente leitura)

@mysql-mcp 查询用户表前10条记录

Gerar documentação da tabela

@mysql-mcp 为users表生成Markdown文档

Gerar visão geral do banco de dados

@mysql-mcp 生成mydb数据库的概览文档

Ferramentas Disponíveis

Nome da Ferramenta	Descrição da Função	Parâmetros Principais
test_connection	Testar conexão com o banco de dados	-
get_security_info	Obter informações de configuração de segurança	-
list_tables	Obter lista de tabelas do banco de dados	database(opcional)
describe_table	Obter estrutura detalhada da tabela	table_name, database(opcional)
generate_table_doc	Gerar documentação da tabela	table_name, format, database(opcional)
generate_database_overview	Gerar visão geral do banco de dados	database(opcional)
execute_query	Executar instrução SQL	sql
list_schemas	Obter lista de bancos de dados disponíveis	-

Notas sobre Geração de Documentação

O recurso de geração de documentação salvará os documentos gerados como arquivos reais:

• Local de salvamento: Pasta docs/ no diretório mysql-mcp
• Nomeação de arquivos: Formato {database}_{table_name}_{timestamp}.{ext}
• Formatos suportados: Markdown (.md), JSON (.json), SQL (.sql)

Exemplo de saída:

✅ 文档生成成功!
📁 保存路径: docs/mydb_users_20250110_142000.md
📂 MCP服务目录: F:/path/to/mysql-mcp
📊 表名: mydb.users
📝 格式: markdown
⏰ 生成时间: 2025-01-10 14:20:00

Gerenciamento de Cache

O serviço fornece funcionalidade de cache de consultas, armazenando automaticamente em cache os resultados de consultas somente leitura:

# 获取缓存统计信息
@mysql-mcp 获取查询缓存统计信息

# 清空缓存
@mysql-mcp 清空查询缓存

Notas de Segurança

1. Ambiente de produção recomenda usar o modo readonly
2. Ambientes sensíveis devem evitar o uso do modo full_access
3. Segurança de senha: Evite usar senhas fracas na configuração
4. Segurança de rede: Garanta que a conexão com o banco de dados use um canal de rede seguro
5. Privilégios mínimos: O usuário do banco de dados deve ter apenas os privilégios mínimos necessários

Tratamento de Erros

• Erro de configuração: Verifique as configurações das variáveis de ambiente na configuração MCP do Cursor
• Falha de conexão: Verifique os parâmetros de conexão do banco de dados e a conectividade de rede
• Permissões insuficientes: Verifique as permissões do usuário do banco de dados e as configurações do modo de segurança
• SQL rejeitado: O modo de segurança atual não permite a execução desse tipo de operação SQL

Arquitetura Técnica

Módulos Principais

• main.py: Programa principal do serviço MCP
• config.py: Módulo de configuração de variáveis de ambiente
• database.py: Módulo de operações de banco de dados e controle de segurança
• document_generator.py: Módulo de geração de documentação

Controle de Segurança

• Validação de modo de segurança em vários níveis
• Verificação de tipo de instrução SQL
• Controle de permissão de acesso ao banco de dados
• Limite de número de linhas nos resultados de consulta
• Mecanismo de tempo limite de conexão e tentativas

Adaptação MySQL

• Usa o driver mysql-connector-python para conexão
• Adapta a sintaxe de consulta das tabelas do sistema MySQL
• Suporta reconhecimento de tipos de restrição MySQL
• Adapta o mapeamento de tipos de dados MySQL

Licença

Este projeto é lançado sob a Licença MIT.

• ✅ Uso livre: Permite que qualquer pessoa use, copie e modifique este software gratuitamente
• ✅ Compatível com uso comercial: Suporta uso e distribuição comercial
• ✅ Liberdade de modificação: Pode modificar o código-fonte e publicar trabalhos derivados
• ✅ Restrições mínimas: Apenas requer a manutenção do aviso de direitos autorais

---

Versão: 1.0.0
Data de atualização: 2025-01-10
Objetivo do design: Otimizado especificamente para integração com banco de dados MySQL e Cursor MCP