convez.ai
MCP ServerIntegração & APIsIntermediário
berthojoris

MySQL MCP Server

berthojoris/mysql-mcp

Integre MySQL ao Claude com permissões dinâmicas e seguras

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor Model Context Protocol para integração de bancos MySQL com agentes de IA, oferecendo controle granular de permissões por projeto. Permite que Claude e outros agentes acessem, consultam e gerenciam dados MySQL de forma segura e produção.

Instalação

$npx convez-ai berthojoris/mysql-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
2
Acompanhando
0
Saúde
28%
Último commit
há 3 semanas
Versão
—
Issues abertas
1
Contribuidores
2

Casos de uso

  • Agentes IA consultando bases de dados em tempo real
  • Automação de consultas e operações MySQL via Claude
  • Desenvolvimento com acesso controlado a múltiplos bancos de dados

Veredito

MCP server robusto e bem documentado para conectar bancos MySQL ao ecossistema Claude. Pronto para produção com sistema de permissões granulares que evita riscos de segurança.

README

A tradução para o português deste README ainda está na fila.

MySQL MCP Server

A production-ready Model Context Protocol (MCP) server for MySQL database integration with AI agents

Last Updated: 2026-05-26 05:08:25

npm version npm downloads License: MIT TypeScript MCP Compatible

Installation · Quick Start · Configuration · Permissions · Tools · Documentation


TL;DR - Quick Setup

Run directly with npx:

npx @berthojoris/mcp-mysql-server mysql://user:pass@localhost:3306/mydb "list,read,utility"

Add to your AI agent config (.mcp.json, .cursor/mcp.json, etc.):

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "type": "stdio",
      "args": [
        "-y",
        "@berthojoris/mcp-mysql-server",
        "mysql://user:pass@localhost:3306/mydb",
        "list,read,utility"
      ]
    }
  }
}

For agent-specific examples (Codex TOML, Zed, local path, multi-DB), see DOCUMENTATIONS.md → Setup & Configuration.


Installation

Option 1: Quick Start with npx (Recommended)

No installation required - run directly:

npx @berthojoris/mcp-mysql-server mysql://user:pass@localhost:3306/db "list,read,utility"

Option 2: Global Installation

npm install -g @berthojoris/mcp-mysql-server
mcp-mysql mysql://user:pass@localhost:3306/db "list,read,utility"

Credentials with special characters: if your username or password contains characters that have a special meaning in URLs (@, :, /, ?, #, %, &, etc.), URL-encode them before putting them in the connection string. For example, the password p@ss:w0rd becomes p%40ss%3Aw0rd, giving mysql://user:p%40ss%3Aw0rd@host:3306/db. The server decodes both the username and password before connecting.


Quick Start

1. Set Up Environment (Optional)

Create .env file for local development:

DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=yourpassword
DB_NAME=yourdatabase
MCP_CONFIG=list,read,utility

2. Build Project (If Cloned Locally)

npm install
npm run build

3. Configure Your AI Agent

See AI Agent Configuration section below.

4. Restart Your AI Agent

Completely restart your AI agent application to load the MCP server.

5. Test It!

Try asking your AI:

"What databases are available?" "Show me all tables in my database" "What's the structure of the users table?" "Show me the first 5 records from users"


AI Agent Configuration

Standard JSON Configuration

Most AI agents use a similar JSON configuration format (the file location varies by tool).

If you want ready-to-copy snippets per client (Claude Code/Cursor/Windsurf/Cline/Codex/Zed), see DOCUMENTATIONS.md → Agent Configuration Examples.

Universal Configuration Template:

Option 1: Single-Layer (Permissions Only) - Simple Setup

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "type": "stdio",
      "args": [
        "-y",
        "@berthojoris/mcp-mysql-server",
        "mysql://user:password@localhost:3306/database",
        "list,read,utility,create,update,ddl"
      ]
    }
  }
}

Option 2: Dual-Layer (Permissions + Categories) - Recommended for Fine Control

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "type": "stdio",
      "args": [
        "-y",
        "@berthojoris/mcp-mysql-server",
        "mysql://user:password@localhost:3306/database_name_here",
        "list,read,utility,create,update,ddl,transaction",
        "database_discovery,crud_operations,custom_queries,schema_management,index_management,constraint_management,table_maintenance,query_optimization,analysis,seed_operations"
      ]
    }
  }
}

💡 Tip: The dual-layer approach provides granular control. The 4th argument (permissions) controls broad access levels, while the 5th argument (categories) fine-tunes which specific tools are available.

Environment Variables Configuration

Alternative approach using environment variables instead of connection string:

Option 1: Permissions Only (Simple)

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "type": "stdio",
      "args": ["-y", "@berthojoris/mcp-mysql-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "root",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database",
        "MCP_PERMISSIONS": "list,read,utility,create,update,delete"
      }
    }
  }
}

Option 2: Permissions + Categories (Recommended)

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "type": "stdio",
      "args": ["-y", "@berthojoris/mcp-mysql-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "root",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database",
        "MCP_PERMISSIONS": "list,read,utility,create,update,delete",
        "MCP_CATEGORIES": "database_discovery,custom_queries,analysis"
      }
    }
  }
}

For more client-specific config snippets, see DOCUMENTATIONS.md → Setup & Configuration.


Cursor Compatibility Bridge

If a Cursor MCP wrapper can call tools but cannot send arguments, use the no-argument cursor_execute_request bridge. Create .cursor/mysql-mcp-request.json in the workspace, then call cursor_execute_request:

{
  "tool": "execute_ddl",
  "arguments": {
    "query": "DROP TABLE IF EXISTS spark_processes;"
  }
}

For direct SQL, the bridge can infer the right SQL tool:

{
  "query": "DROP TABLE IF EXISTS spark_processes;",
  "mode": "auto"
}

Set MYSQL_MCP_CURSOR_REQUEST_FILE to override the request file path.


AI Agent Tool Discovery

For Codex, Claude Code CLI, Cursor, Droid CLI, and other MCP agents, call list_all_tools first. It returns the live runtime catalog, enabled/disabled status, active permission/category profile, and recommended workflows for schema exploration, safe SELECT queries, CSV exports, transactions, and data changes.

Use export_table_to_csv for table-based exports and export_query_to_csv for SELECT query exports.


Permission System

Control database access with a dual-layer filtering system that provides both broad and fine-grained control:

  • Layer 1 (Permissions): Broad operation-level control using legacy categories
  • Layer 2 (Categories): Optional fine-grained tool-level filtering using documentation categories

Filtering Logic: Tool enabled = (Has Permission) AND (Has Category OR No categories specified)

Permissions

PermissionOperationsUse Case
listList databases, tables, schemasDatabase exploration
readSELECT queries, read dataAnalytics, reporting
createINSERT new recordsData entry
updateUPDATE existing recordsData maintenance
deleteDELETE recordsData cleanup
executeExecute custom INSERT/UPDATE SQL (DELETE requires delete permission too)Complex write operations
ddlCREATE/ALTER/DROP tablesSchema management
procedureStored procedures (CREATE/DROP/EXECUTE)Procedure management
transactionBEGIN, COMMIT, ROLLBACKACID operations
utilityConnection testing, diagnosticsTroubleshooting

Common configuration examples are documented in DOCUMENTATIONS.md → Category Filtering System.


Documentation Categories (Recommended)

Use documentation categories to fine-tune which tools are exposed (Layer 2):

Category ListUse CaseList Tools
database_discoveryExplore databases, tables, and schema structureget_all_tables_relationships, list_databases, list_tables, read_table_schema
crud_operationsCreate, read, update, delete operations on datacreate_record, delete_record, read_records, update_record
bulk_operationsHigh-performance batch processing operationsbulk_delete, bulk_insert, bulk_update
seed_operationsFK-aware relational dummy data seedingexecute_seed_plan, generate_seed_preview, infer_seed_rules, plan_seed_data, seed_from_template, validate_seed_integrity
custom_queriesExecute custom SQL queries and advanced operationsexecute_write_query, run_select_query
schema_managementManage database schema, tables, and structurealter_table, create_table, drop_table, execute_ddl
utilitiesDatabase utilities, diagnostics, and helper functionscursor_execute_request, describe_connection, export_query_to_csv, export_table_to_csv, list_all_tools, read_changelog, test_connection
transaction_managementHandle ACID transactions and rollback operationsbegin_transaction, commit_transaction, execute_in_transaction, get_transaction_status, rollback_transaction
stored_proceduresCreate, execute, and manage stored procedurescreate_stored_procedure, drop_stored_procedure, execute_stored_procedure, get_stored_procedure_info, list_stored_procedures, show_create_procedure
views_managementCreate and manage database viewsalter_view, create_view, drop_view, get_view_info, list_views, show_create_view
triggers_managementCreate and manage database triggerscreate_trigger, drop_trigger, get_trigger_info, list_triggers, show_create_trigger
index_managementOptimize performance with index managementanalyze_index, create_index, drop_index, get_index_info, list_indexes
constraint_managementManage data integrity constraintsadd_check_constraint, add_foreign_key, add_unique_constraint, drop_constraint, drop_foreign_key, list_constraints, list_foreign_keys
table_maintenanceTable optimization, repair, and maintenanceanalyze_table, check_table, flush_table, get_table_size, get_table_status, optimize_table, repair_table, truncate_table
query_optimizationAnalyze and optimize SQL queriesanalyze_query, get_optimization_hints
analysisData analysis, schema discovery, and reporting toolsfind_tables_by_keyword, get_column_statistics, get_database_summary, get_schema_erd, get_schema_rag_context, search_data_across_tables, search_schema
database_discovery,crud_operations,bulk_operations,seed_operations,custom_queries,schema_management,utilities,transaction_management,stored_procedures,views_management,triggers_management,index_management,constraint_management,table_maintenance,query_optimization,analysis

Full category → tool mapping (and examples) lives in DOCUMENTATIONS.md → Category Filtering System.


Available Tools

The server exposes 88 tools organized into categories (CRUD, seed, schema, discovery, and utilities).


Detailed Documentation

For comprehensive documentation, see DOCUMENTATIONS.md:

  • DDL Operations - Create, alter, and drop tables
  • Data Export Tools - Export to CSV, JSON, and SQL formats
  • Relational Data Seeder - Plan, preview, execute, validate, infer rules, and template FK-aware dummy data
  • Data Import Tools - Import from CSV and JSON sources
  • Data Migration Tools - Copy, move, clone, compare, and sync data
  • Schema Versioning - Version control for database schema changes
  • Transaction Management - ACID transactions
  • Stored Procedures - Create and execute with IN/OUT/INOUT parameters
  • Query Logging - See all SQL queries executed automatically
  • Security Features - Built-in security and best practices
  • Bulk Operations - High-performance batch processing
  • Troubleshooting - Common issues and solutions

MySQL MCP vs Manual Database Access

This MySQL MCP is a powerful intermediary layer between AI assistants and MySQL databases.

For full feature coverage and usage examples, see DOCUMENTATIONS.md.


License

MIT License - see LICENSE file for details.


Made with care for the AI development community

Enabling AI agents to interact with MySQL databases safely and efficiently

Report Bug · Request Feature · Documentation

Ver o original no GitHub

Bom para

Relacionados