Mysql Server

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

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):

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).

• Complete list of tools: DOCUMENTATIONS.md → Complete Tools Reference

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.