MySQL MCP Server

Um servidor de banco de dados MySQL para assistentes de IA, permitindo operações CRUD completas, gerenciamento de transações e rollback inteligente.

GitHub

Experimente este MCPPatrocinado

Documentação

MySQL MCP Server 🚀

v4.0.0 - Reescrita com nova arquitetura, mais simples e mais poderosa!

Um servidor MCP (Model Context Protocol) MySQL poderoso e fácil de usar, que permite que assistentes de IA operem bancos de dados MySQL com segurança.

🌟 Recursos Principais

🌐 Protocolo StreamableHTTP - Implementado com base nas especificações MCP mais recentes
🔐 Pré-configuração de Headers - Credenciais não expostas à IA, seguro e confiável
🤖 Gerenciamento Dinâmico por IA - A IA pode adicionar/alternar conexões de banco de dados para você
🔗 Suporte a Múltiplos Bancos - Gerencie vários bancos de dados simultaneamente, alternando quando necessário
📊 CRUD Completo - Suporta todas as operações SQL
🏗️ Arquitetura Modular - Estrutura de diretórios clara, fácil de estender

📦 Instalação

Requisitos do Ambiente

Node.js 18+
MySQL 5.7+ ou 8.0+
Cliente MCP (Claude Desktop, Cursor, etc.)

Passos de Instalação

# 克隆项目
git clone https://github.com/guangxiangdebizi/MySQL_MCP.git
cd MySQL_MCP

# 安装依赖
npm install

# 编译
npm run build

# 启动服务器
npm start

⚙️ Métodos de Configuração

Método 1: Pré-configuração de Headers (Recomendado)

Edite o arquivo de configuração do MCP:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Configuração de Banco Único

{
  "mcpServers": {
    "mysql-mcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "timeout": 600,
      "headers": {
        "X-MySQL-Host": "localhost",
        "X-MySQL-Port": "3306",
        "X-MySQL-User": "root",
        "X-MySQL-Password": "your_password",
        "X-MySQL-Database": "your_database"
      }
    }
  }
}

Configuração de Múltiplos Bancos

{
  "mcpServers": {
    "mysql-mcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "timeout": 600,
      "headers": {
        "X-MySQL-Host-1": "prod.mysql.com",
        "X-MySQL-User-1": "prod_user",
        "X-MySQL-Password-1": "prod_pass",
        "X-MySQL-Database-1": "production",
        
        "X-MySQL-Host-2": "test.mysql.com",
        "X-MySQL-User-2": "test_user",
        "X-MySQL-Password-2": "test_pass",
        "X-MySQL-Database-2": "testing"
      }
    }
  }
}

Vantagens:

✅ Credenciais do banco de dados não expostas à IA
✅ Conecta na inicialização, sem necessidade de operação manual
✅ Suporta conexão simultânea a múltiplos bancos de dados

Método 2: Adição Dinâmica por IA (Flexível)

Sem configurar Headers, deixe a IA adicionar conexões durante a conversa:

{
  "mcpServers": {
    "mysql-mcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "timeout": 600
    }
  }
}

Exemplo de uso:

你: 帮我连接到本地 MySQL，用户名 root，密码 123456，数据库 mydb
AI: [调用 add_connection 工具]

🔧 Lista de Ferramentas

Gerenciamento de Conexões

Nome da Ferramenta	Descrição	Cenário de Uso
`add_connection`	Adicionar conexão de banco de dados	A IA adiciona dinamicamente novas conexões
`list_connections`	Listar todas as conexões	Visualizar quais bancos de dados estão disponíveis
`select_database`	Selecionar banco de dados ativo	Alternar para outro banco de dados
`remove_connection`	Remover conexão	Limpar conexões desnecessárias

Operações de Consulta

Nome da Ferramenta	Descrição	Cenário de Uso
`execute_query`	Executar SQL	Qualquer operação SQL (SELECT, INSERT, UPDATE, DELETE)
`show_tables`	Mostrar todas as tabelas	Entender rapidamente a estrutura do banco de dados
`describe_table`	Visualizar estrutura da tabela	Visualizar campos, tipos, dados de exemplo
`show_databases`	Mostrar todos os bancos de dados	Visualizar lista de bancos de dados acessíveis

🎮 Exemplos de Uso

Cenário 1: Usando Pré-configuração de Headers

你: 显示所有表
AI: [调用 show_tables] 
    📊 数据库表列表 (共 5 个表)
    1. users
    2. orders
    3. products
    ...

你: 查看 users 表的结构
AI: [调用 describe_table，参数：users]
    📋 表结构: users
    字段信息:
    - id (INT, 主键)
    - name (VARCHAR)
    - email (VARCHAR)
    ...

Cenário 2: Adição Dinâmica de Conexão pela IA

你: 帮我连接两个数据库：
    1. 生产库：prod.mysql.com，用户 admin，密码 xxx，数据库 shop
    2. 测试库：test.mysql.com，用户 tester，密码 yyy，数据库 shop_test

AI: [调用 add_connection，参数：id=prod, host=prod.mysql.com...]
    [调用 add_connection，参数：id=test, host=test.mysql.com...]
    ✅ 两个数据库连接已添加

你: 列出所有连接
AI: [调用 list_connections]
    📊 当前数据库连接列表 (共 2 个)
    🟢 [1] prod
       └─ prod.mysql.com:3306/shop
       └─ ✅ 当前活跃连接
    ⚪ [2] test
       └─ test.mysql.com:3306/shop_test

你: 切换到测试库
AI: [调用 select_database，参数：test]
    ✅ 已选择数据库: test

你: 查询用户表前 10 条
AI: [调用 execute_query，SQL: SELECT * FROM users LIMIT 10]
    ✅ 查询成功，返回 10 行数据
    [显示 JSON 格式数据]

🏗️ Arquitetura do Projeto

MySQL_MCP/
├── src/
│   ├── index.ts              # 主入口（HTTP Server + 会话管理）
│   ├── database.ts           # 数据库连接管理器
│   └── tools/                # 工具模块
│       ├── index.ts          # 工具统一导出和路由
│       ├── connection.ts     # 连接管理工具
│       └── query.ts          # 查询工具
├── dist/                     # 编译后的 JS 文件
├── package.json
├── tsconfig.json
└── README.md

Design Principal:

index.ts - Servidor HTTP Express + Inicialização do MCP Server
database.ts - Encapsula o pool de conexões do banco de dados e a lógica de consulta
tools/ - Cada arquivo é responsável pela definição e processamento de uma categoria de ferramentas

🔒 Recomendações de Segurança

Configuração de Permissões do Banco de Dados

Crie um usuário de banco de dados dedicado para o MCP, com permissões limitadas:

-- 创建专用用户
CREATE USER 'mcp_user'@'%' IDENTIFIED BY 'strong_password';

-- 授予必要权限
GRANT SELECT, INSERT, UPDATE, DELETE ON your_database.* TO 'mcp_user'@'%';

-- 生产环境只读用户
GRANT SELECT ON your_database.* TO 'mcp_readonly'@'%';

Segurança no Modo HTTP

✅ Use pré-configuração de Headers para evitar exposição de credenciais à IA
✅ Use HTTPS em produção (proxy reverso Nginx)
✅ Restrinja IPs de acesso (regras de firewall)
✅ Atualize senhas do banco de dados regularmente
✅ Monitore logs para detectar acessos anômalos

🚀 Scripts NPM

# 开发模式（TypeScript 直接运行）
npm run dev

# 编译
npm run build

# 生产模式（运行编译后的 JS）
npm start

# 全局安装
npm run install-global

📝 Variáveis de Ambiente

Crie o arquivo .env (opcional):

# HTTP 服务器端口
PORT=3001

# Node 环境
NODE_ENV=production

❗ Perguntas Frequentes

1. Porta em uso

Erro: EADDRINUSE: address already in use :::3001

Solução: Modifique .env no arquivo PORT, ou encerre o processo que está usando a porta

# Windows
netstat -ano | findstr :3001
taskkill /F /PID <PID>

# Linux/Mac
lsof -ti:3001 | xargs kill -9

2. Falha na conexão

Erro: 数据库连接失败

Verifique:

Se o serviço MySQL está em execução
Se host, porta, usuário e senha estão corretos
Se o firewall permite a conexão

3. Sessão perdida

Problema: Mensagem "Session not found" após reiniciar o servidor

Causa: As sessões são armazenadas em memória e são limpas após reinicialização

Solução: Atualize o cliente MCP (reinicie a inicialização)

4. Erro de conexão fechada

Erro: Can't add new command when connection is in closed state

Causa:

Conexão do banco de dados ociosa por muito tempo, o servidor MySQL fechou a conexão
Interrupção de rede causou desconexão

Solução:

✅ A partir da v4.0.5+, o pool de conexões substitui a conexão única, com suporte automático a:
- Mecanismo de Keep-Alive
- Recurso de reconexão automática
- Suporte a consultas concorrentes
Se o problema persistir, reinicie o servidor MCP

📦 Histórico de Versões

v4.0.5 (2025-12-09) - Otimização do Pool de Conexões

🎯 Uso de pool de conexões em vez de conexão única
🔄 Keep-Alive automático
🔌 Mecanismo de reconexão automática
🚀 Suporte a consultas concorrentes
🐛 Correção do erro "connection in closed state"

v4.0.0 (2025-12-09) - Nova Arquitetura

🔥 Reescrita completa, nova arquitetura modular
✨ Baseado no protocolo MCP StreamableHTTP mais recente
🎯 Ferramentas simplificadas: gerenciamento de conexões + operações de consulta
🏗️ Estrutura de diretórios clara: tools/ modular
🚀 Resposta mais rápida
📖 Comentários de código mais claros

v3.x - Versões Anteriores

Suporte a gerenciamento de transações, rollback e outras funcionalidades complexas
Arquitetura mais complexa

📞 Suporte e Feedback

🐛 Relatar Problemas: GitHub Issues
💡 Sugestões de Funcionalidades: GitHub Discussions
📧 Contato do Autor: guangxiangdebizi@gmail.com

🔧 Solução de Problemas

Problema: Erro `ERR_MODULE_NOT_FOUND`

Mensagem de erro:

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '...@modelcontextprotocol/sdk...'

Soluções:

Exclua e reinstale as dependências:

# 删除旧依赖
rm -rf node_modules package-lock.json  # Linux/Mac
# 或
rmdir /s /q node_modules && del package-lock.json  # Windows

# 清理缓存
npm cache clean --force

# 重新安装
npm install

Verifique a versão do Node.js:

node --version  # 需要 >= 18.0.0

Use instalação global:

npm install -g @xingyuchen/mysql-mcp-server@latest

Problema: Desconexão do fluxo SSE

Mensagem de erro:

SSE stream disconnected: TypeError: terminated

Soluções:

Defina um timeout maior ou desative o timeout em mcp.json:

{
  "mysql-mcp-http": {
    "type": "streamableHttp",
    "url": "http://localhost:3002/mcp",
    "timeout": 0,  // 0 表示无超时限制
    "headers": { ... }
  }
}

Problema: Aviso de vulnerabilidade de segurança

Mensagem de aviso:

npm audit: vulnerabilities found

Soluções:

# 自动修复
npm audit fix

# 如果还有问题，强制修复
npm audit fix --force

# 重新构建
npm run build

Problema: Porta em uso

Mensagem de erro:

Error: listen EADDRINUSE: address already in use :::3002

Soluções:

Altere a porta (no arquivo .env):

PORT=3003

Ou encerre o processo que está usando a porta:

# Windows
netstat -ano | findstr :3002
taskkill /PID <进程ID> /F

# Linux/Mac
lsof -i :3002
kill -9 <进程ID>

Obter mais ajuda

📄 Licença

Licença Apache 2.0 - Consulte o arquivo LICENSE

⭐ Se este projeto foi útil para você, dê uma estrela para apoiar!

MySQL MCP Server

Documentação

MySQL MCP Server 🚀

🌟 Recursos Principais

📦 Instalação

Requisitos do Ambiente

Passos de Instalação

⚙️ Métodos de Configuração

Método 1: Pré-configuração de Headers (Recomendado)

Configuração de Banco Único

Configuração de Múltiplos Bancos

Método 2: Adição Dinâmica por IA (Flexível)

🔧 Lista de Ferramentas

Gerenciamento de Conexões

Operações de Consulta

🎮 Exemplos de Uso

Cenário 1: Usando Pré-configuração de Headers

Cenário 2: Adição Dinâmica de Conexão pela IA

🏗️ Arquitetura do Projeto

🔒 Recomendações de Segurança

Configuração de Permissões do Banco de Dados

Segurança no Modo HTTP

🚀 Scripts NPM

📝 Variáveis de Ambiente

❗ Perguntas Frequentes

1. Porta em uso

2. Falha na conexão

3. Sessão perdida

4. Erro de conexão fechada

📦 Histórico de Versões

v4.0.5 (2025-12-09) - Otimização do Pool de Conexões

v4.0.0 (2025-12-09) - Nova Arquitetura

v3.x - Versões Anteriores

📞 Suporte e Feedback

🔧 Solução de Problemas

Problema: Erro ERR_MODULE_NOT_FOUND

Problema: Desconexão do fluxo SSE

Problema: Aviso de vulnerabilidade de segurança

Problema: Porta em uso

Obter mais ajuda

📄 Licença

Problema: Erro `ERR_MODULE_NOT_FOUND`