MySQL Shell
Value Proposition Enable AI agents to perform parallel imports and full instance dumps. Establish clear administrative boundaries and securely orchestrate complex database scripts. Read the full value proposition
- MySQL Shell binary accessible (in PATH or via environment variable)
- Version Compatibility: MySQL Shell version should match your MySQL Server version.
The server provides tools for MySQL Shell management. Direct users to the native MCP discovery mechanism or the mysql_tool_index prompt to explore the complete list of available tools. Ecosystem tools (Router, Shell) are conditionally loaded only when their respective binaries and credentials are detected.
Prominent Examples:
-
mysqlsh_version: Get MySQL Shell version and installation status. -
mysqlsh_dump_instance: Dump entire MySQL instance. -
mysqlsh_load_dump: Load MySQL Shell dump.
| Tool | Requirements |
|---|---|
mysqlsh_import_json |
Requires X Protocol (typically port 33060) for collection imports. NDJSON format only |
mysqlsh_import_table |
Requires target tables to have a PRIMARY KEY when importing to InnoDB Cluster |
mysqlsh_load_dump / mysqlsh_import_table
|
Requires local_infile=ON in MySQL Server config. Use SET GLOBAL local_infile = 1; or configure it in my.cnf. |
mysqlsh_check_upgrade |
User needs RELOAD, PROCESS, SELECT privileges |
mysqlsh_dump_* / mysqlsh_load_dump
|
Shell version should match server version |
mysqlsh_* |
Operates under standard execution boundaries. When OAuth is enabled, the shell tools require the admin scope. |
Ensure execution of database migrations by verifying your environment against these operational baselines:
mysqlsh --version
# Expected: mysqlsh Ver <version> for ...SET GLOBAL local_infile = 1;Or add to my.cnf:
[mysqld]
local_infile=ONmysqlsh --uri root@localhost:33060 --sql -e "SELECT 1"| Variable | Default | Description |
|---|---|---|
MYSQLSH_PATH |
mysqlsh |
Path to MySQL Shell binary |
MYSQLSH_WORK_DIR |
Current directory | Working directory for dump/load operations |
MYSQLSH_TIMEOUT |
300000 |
Command timeout in milliseconds (5 min) |
MYSQL_XPORT |
33060 |
X Protocol port (for mysqlsh_import_json). Intentionally used instead of the standard MYSQLX_PORT. |
Warning
Shell operations may exceed default HTTP timeouts. Increase MCP_REQUEST_TIMEOUT to prevent dropped connections. This applies specifically to HTTP/SSE clients, not standard stdio. When running heavy HTTP migrations, explicitly align MCP_REQUEST_TIMEOUT with MYSQLSH_TIMEOUT.
Warning
MySQL Shell commands execute as subprocesses. Ensure proper file permissions. Configure --allowed-io-roots to permit sandbox access.
{
"mcpServers": {
"mysql-mcp": {
"command": "npx",
"args": [
"-y",
"@neverinfamous/mysql-mcp",
"--transport",
"stdio",
"--mysql",
"mysql://user:password@localhost:3306/database",
"--allowed-io-roots",
"C:/temp,/tmp"
],
"env": {
"MYSQLSH_PATH": "mysqlsh"
}
}
}
}Note
Global install users can substitute npx -y @neverinfamous/mysql-mcp with mysql-mcp.
For environments requiring workload isolation:
{
"mcpServers": {
"mysql-mcp": {
"command": "npx",
"args": [
"-y",
"@neverinfamous/mysql-mcp",
"--transport",
"stdio",
"--mysql",
"mysql://user:password@localhost:3306/database",
"--allowed-io-roots",
"C:/temp,/tmp",
"--tool-filter",
"shell"
]
}
}
}This exposes only the MySQL Shell management tools.
Note
OAuth requires the http transport. Desktop clients (such as Claude Desktop and Cursor) using mcp.json and stdio cannot natively use OAuth. See OAuth Configuration for details.
The MCP server automatically validates all tool parameters before execution using Zod for Standard Schema validation and safe parsing best practices. This ensures reliable operations and prevents invalid arguments from reaching MySQL Shell by gracefully rejecting hallucinated payloads.
- Tools - Complete tool list
- Tool Filtering - Custom tool filtering
- Configuration - General configuration