MySQL MCP Server

<div align="center">

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

Last Updated: 2026-01-25 14:00:00

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

</div>

---

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"

---

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",
        "database_discovery,crud_operations,custom_queries,schema_management,index_management,constraint_management,table_maintenance,query_optimization,analysis"
      ]
    }
  }
}

💡 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,performance_monitoring,custom_queries"
      }
    }
  }
}

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

---

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

Permission	Operations	Use Case
list	List databases, tables, schemas	Database exploration
read	SELECT queries, read data	Analytics, reporting
create	INSERT new records	Data entry
update	UPDATE existing records	Data maintenance
delete	DELETE records	Data cleanup
execute	Execute custom SQL (DML) + Advanced SQL	Complex operations
ddl	CREATE/ALTER/DROP tables	Schema management
procedure	Stored procedures (CREATE/DROP/EXECUTE)	Procedure management
transaction	BEGIN, COMMIT, ROLLBACK	ACID operations
utility	Connection testing, diagnostics	Troubleshooting

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 List	Use Case	List Tools
database_discovery	Explore databases, tables, and schema structure	get_all_tables_relationships, get_table_relationships, list_databases, list_tables, read_table_schema
crud_operations	Create, read, update, delete operations on data	create_record, delete_record, read_records, update_record
bulk_operations	High-performance batch processing operations	bulk_delete, bulk_insert, bulk_update
custom_queries	Execute custom SQL queries and advanced operations	execute_write_query, run_select_query
schema_management	Manage database schema, tables, and structure	alter_table, create_table, drop_table, execute_ddl
utilities	Database utilities, diagnostics, and helper functions	describe_connection, export_query_to_csv, export_table_to_csv, list_all_tools, read_changelog, test_connection
transaction_management	Handle ACID transactions and rollback operations	begin_transaction, commit_transaction, execute_in_transaction, get_transaction_status, rollback_transaction
stored_procedures	Create, execute, and manage stored procedures	create_stored_procedure, drop_stored_procedure, execute_stored_procedure, get_stored_procedure_info, list_stored_procedures, show_create_procedure
views_management	Create and manage database views	alter_view, create_view, drop_view, get_view_info, list_views, show_create_view
triggers_management	Create and manage database triggers	create_trigger, drop_trigger, get_trigger_info, list_triggers, show_create_trigger
functions_management	Create and manage database functions	create_function, drop_function, execute_function, get_function_info, list_functions, show_create_function
index_management	Optimize performance with index management	analyze_index, create_index, drop_index, get_index_info, list_indexes
constraint_management	Manage data integrity constraints	add_check_constraint, add_foreign_key, add_unique_constraint, drop_constraint, drop_foreign_key, list_constraints, list_foreign_keys
table_maintenance	Table optimization, repair, and maintenance	analyze_table, check_table, flush_table, get_table_size, get_table_status, optimize_table, repair_table, truncate_table
server_management	MySQL server configuration and administration	explain_query, get_server_info, kill_process, show_binary_logs, show_engine_status, show_process_list, show_replication_status, show_status, show_variables
performance_monitoring	Monitor and analyze database performance	get_connection_pool_stats, get_database_health_check, get_index_usage_stats, get_performance_metrics, get_slow_queries, get_table_io_stats, get_top_queries_by_count, get_top_queries_by_time, get_unused_indexes, reset_performance_stats
cache_management	Manage query cache and optimization	clear_cache, configure_cache_settings, get_cache_config, get_cache_stats, invalidate_cache_for_table
query_optimization	Analyze and optimize SQL queries	analyze_query, get_optimization_hints
backup_restore	Create backups and restore databases	backup_database, backup_table, get_create_table_statement, get_database_schema, restore_from_sql
import_export	Import and export data in various formats	export_query_to_json, export_table_to_json, export_table_to_sql, import_from_csv, import_from_json, safe_export_table
data_migration	Migrate data between databases or systems	clone_table, compare_table_structure, copy_table_data, move_table_data, sync_table_data
schema_migrations	Version control for database schema changes	apply_migrations, create_migration, generate_migration_from_diff, get_migration_status, get_schema_version, init_migrations_table, reset_failed_migration, rollback_migration, validate_migrations
analysis	Data analysis and reporting tools	get_column_statistics, get_database_summary, get_schema_erd, get_schema_rag_context
ai_enhancement	AI-powered features and smart automation	analyze_schema_patterns, audit_database_security, build_query_from_intent, design_schema_from_requirements, discover_data_patterns, find_similar_columns, forecast_database_growth, generate_business_glossary, generate_data_dictionary, generate_documentation, generate_test_data, predict_query_performance, recommend_indexes, smart_search, suggest_query_improvements, visualize_query

<details> <summary>Copy/paste list (comma-separated, no spaces)</summary>

database_discovery,crud_operations,bulk_operations,custom_queries,schema_management,utilities,transaction_management,stored_procedures,views_management,triggers_management,functions_management,index_management,constraint_management,table_maintenance,server_management,performance_monitoring,cache_management,query_optimization,backup_restore,import_export,data_migration,schema_migrations,analysis,ai_enhancement

</details>

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

---

Available Tools

The server exposes 150 tools organized into categories (CRUD, schema, backups, migrations, perf/monitoring, and AI enhancement).

• Complete list of tools: DOCUMENTATIONS.md → Complete Tools Reference
• AI enhancement tools overview: DOCUMENTATIONS.md → AI Enhancement Tools

🤖 AI Enhancement Tools

The full Phase 1–3 (implemented) overview, examples, and per-tool documentation lives in DOCUMENTATIONS.md.

---

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
• Data Import Tools - Import from CSV and JSON sources
• Database Backup & Restore - Full backup/restore with SQL dumps
• 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
• 🤖 AI Enhancement - Natural language to SQL, smart data discovery, schema design, security audit, index recommendations, data generation, visualization, and forecasting (Phase 1-3)
• 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.

---

<div align="center">

Made with care for the AI development community

Enabling AI agents to interact with MySQL databases safely and efficiently

Report Bug · Request Feature · Documentation

</div>