MySQL MCP Server

# mysql-mcp v2.3.0 Release Notes **Release Date:** February 18, 2026 **Status:** Production/Stable --- ## 🎉 Release Highlights **mysql-mcp v2.3.0** introduces **Code Mode** — a sandboxed JavaScript/TypeScript execution environment that lets AI agents compose multi-step MySQL workflows in a single tool call, reducing token usage by 70–90%. This release also adds **Parameter Aliases** (Split Schema) for more natural tool inputs, a configurable `--server-host` CLI option, and delivers **55+ bug fixes** across nearly every tool group — including many fixes to tools that existed before Code Mode. ### At a Glance - **1 Major Feature** — Code Mode (`mysql_execute_code`): 22 API groups, 168+ methods, VM-based sandboxed execution - **3 New Capabilities** — Parameter Aliases (Split Schema), `--server-host` CLI option, Stale Router Detection - **~55 Bug Fixes** — Code mode group registrations, tool help examples, text tool schema violations, event SQL ordering, timer overflows, spatial precision, error handling improvements - **3 Security Items** — CodeQL temp file hardening, `ajv` ReDoS CVE, `qs` DoS CVE - **5 Dependency Bumps** — eslint 10.x, mysql2, @types/node, typescript-eslint --- ## ⚡ Code Mode (`mysql_execute_code`) The headline feature of v2.3.0. Code Mode provides a sandboxed `mysql.*` API namespace enabling AI agents to execute multi-step database workflows as JavaScript/TypeScript code in a single tool call. ### Key Capabilities | Feature | Details | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **22 API Groups** | `mysql.core`, `mysql.json`, `mysql.transactions`, `mysql.spatial`, `mysql.stats`, `mysql.security`, `mysql.cluster`, `mysql.router`, and 14 more | | **168+ Methods** | Full coverage of all mysql-mcp tools | | **VM Isolation** | Sandboxed execution with security validation and rate limiting | | **Auto-Cleanup** | Automatic transaction rollback on completion — no dangling locks | | **Help System** | `mysql.help()` and `mysql.{group}.help()` for introspection | | **Token Savings** | 70–90% reduction vs. individual tool calls for multi-step operations | ### API Groups `core` · `json` · `text` · `fulltext` · `performance` · `optimization` · `admin` · `monitoring` · `backup` · `replication` · `partitioning` · `schema` · `shell` · `events` · `sysschema` · `stats` · `spatial` · `security` · `roles` · `docstore` · `cluster` · `router` ### Auto-Injection Code Mode is automatically included in all preset shortcuts (`starter`, `essential`, `dev-power`, etc.) and is auto-injected when using raw group filters (e.g., `--tool-filter core`). Explicit exclusion via `-codemode` is respected. --- ## 🆕 Parameter Aliases (Split Schema) Tools now accept alternative parameter names for commonly used fields, normalized automatically via Zod schema preprocessing: | Alias | Canonical | Applies To | | ------------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `table` / `tableName` / `name` | table parameter | Core, Text, Backup, Partitioning, Performance, Admin | | `query` / `sql` | query parameter | `mysql_read_query`, `mysql_write_query`, `mysql_explain`, `mysql_explain_analyze`, `mysql_query_rewrite`, `mysql_optimizer_trace` | | `where` / `filter` | WHERE clause | `mysql_export_table` and all Text tools | | `column` / `col` | column parameter | Text tools | Schema definitions use a **Dual-Schema pattern**: `SchemaBase` (with aliases visible to MCP clients) for `inputSchema`, and the runtime `Schema` (with preprocessing + transformation) for handler validation. --- ## 🔒 Security ### CVE Fixes - **`ajv` ReDoS via `$data` Option (GHSA-2g4f-4pwh-qvx6)** — Overrode transitive `ajv` from 8.17.1 to 8.18.0 to fix ReDoS vulnerability in runtime regex patterns - **`qs` ArrayLimit Bypass (GHSA-w7fw-mjwx-w883)** — Updated transitive `qs` from 6.14.1 to 6.14.2 to fix DoS via comma parsing bypass ### CodeQL Remediation - **`mysqlsh_run_script` Secure Temporary File Handling** — Replaced insecure `os.tmpdir()` with `fs.mkdtemp()` for SQL script temp files, eliminating predictable file paths flagged by CodeQL --- ## 🐛 Bug Fixes (Highlights) ### Code Mode Group Registration Fixes Five tool groups were completely inaccessible in Code Mode due to prefix-stripping misconfigurations. All returned `TypeError: ... is not a function`: | Group | Tools Affected | Root Cause | | ------------ | -------------- | ------------------------------ | | **Security** | 9 tools | `security` in `keepPrefix` set | | **Stats** | 8 tools | `stats` in `keepPrefix` set | | **Spatial** | 12 tools | `spatial` in `keepPrefix` set | | **Router** | 9 tools | `router` in `keepPrefix` set | | **Shell** | 10 tools | Missing `groupPrefixMap` entry | ### Code Mode Help Example Fixes Corrected inaccurate parameter names and method references in `help()` output for: `backup`, `optimization`, `security`, `stats`, `spatial`, `json`, `sysschema`, `cluster`, `replication`, `router`, and `shell` groups. ### Non-Code-Mode Bug Fixes These fixes affect tools that existed in v2.2.0: - **`mysql_event_alter` Clause Ordering** — Generated invalid SQL when combining `newName` with other clauses. Reordered to match MySQL's required syntax - **`mysql_explain` TRADITIONAL Format** — Returned TREE format when TRADITIONAL was requested. Now explicitly uses `EXPLAIN FORMAT=TRADITIONAL` - **Text Tool Schema Violations** — `mysql_substring`, `mysql_concat`, `mysql_collation_convert` lacked parameter alias support. Replaced with proper Dual-Schema definitions - **Timer Overflow Detection** — `mysql_slow_queries` / `mysql_query_stats` returned absurdly large values (~213 days) due to unsigned 64-bit picosecond counter wrapping. Now clamped to `-1` with `overflow: true` - **Timer Value Type Consistency** — Non-overflowed timer values returned as strings instead of numbers. Now consistently numbers - **`mysql_security_mask_data`** — Three fixes: credit card 8-digit boundary masking, warning message accuracy, partial masking silent no-op detection - **`mysql_spatial_create_index`** — Duplicate index error consistency and duplicate column index detection - **`mysql_spatial_buffer` Precision** — Added `precision` parameter (default: 6) to control GeoJSON decimal places, significantly reducing payload size for geographic buffers - **`mysql_json_update` Missing Reason** — Now returns `{ success: false, reason }` when target row doesn't exist - **`mysql_json_validate` Auto-Conversion** — Removed auto-conversion that made it impossible to return `valid: false` - **`mysql_read_query` / `mysql_write_query`** — Uniform structured error handling (`{ success: false, error }`) for all query errors - **`mysql_buffer_pool_stats` Payload Reduction** — Curated 23 operationally meaningful columns instead of all 32 - **`mysql_query_rewrite` / `mysql_optimizer_trace`** — Missing `sql` alias for `query` parameter - **`mysql_explain_analyze`** — Missing `sql` alias for `query` parameter - **`mysql_transaction_execute`** — Empty statements now return structured error instead of Zod validation error - **`mysql_event_create`** — Informative existing event messaging with `{ skipped: true, reason }` - **`mysql_sys_memory_summary` / `mysql_sys_schema_stats`** — Added missing count fields for response consistency - **Partitioning Write Tools** — `mysql_add_partition`, `mysql_drop_partition`, `mysql_reorganize_partition` now perform P154 existence checks - **`mysql_router_pool_status`** — Enabled Router connection pool REST API infrastructure - **`mysqlsh_export_table`** — Shell dump-specific error extraction instead of generic privilege-hint message - **`mysqlsh_load_dump`** — Dry run now captures and returns `dryRunOutput` field - **Code Mode Auto-Rollback** — Fixed orphaned transaction cleanup to run unconditionally, not just on failure - **Code Mode Negative Memory Metric** — Clamped to `Math.max(0, ...)` when GC reclaims heap between snapshots --- ## ✨ New Features ### `mysql_cluster_router_status` Stale Router Detection Router responses now include `isStale` boolean per router (true when `lastCheckIn` is null or >1 hour old) and a top-level `staleCount` field, making stale/abandoned router entries immediately identifiable. ### `--server-host` CLI Option / `MCP_HOST` Environment Variable Configurable host binding for HTTP/SSE transport. Defaults to `localhost`. Set to `0.0.0.0` for containerized deployments. --- ## 📦 Dependencies - `@eslint/js` `^9.39.2` → `^10.0.1` - `@types/node` `^25.2.2` → `^25.2.3` - `eslint` `^9.39.2` → `^10.0.0` - `mysql2` `^3.16.3` → `^3.17.2` - `typescript-eslint` `^8.54.0` → `^8.56.0` --- ## 📦 Installation & Upgrade ### Docker (Recommended) ```bash # Latest v2.3.0 docker pull writenotenow/mysql-mcp:v2.3.0 docker pull writenotenow/mysql-mcp:latest # Run with stdio transport docker run -i --rm writenotenow/mysql-mcp:v2.3.0 \ --transport stdio \ --mysql mysql://user:password@host.docker.internal:3306/database ``` ### NPM ```bash npm install -g @neverinfamous/mysql-mcp@2.3.0 ``` ### From Source ```bash git clone https://github.com/neverinfamous/mysql-mcp.git cd mysql-mcp git checkout v2.3.0 npm install npm run build node dist/cli.js --transport stdio --mysql mysql://user:pass@localhost:3306/db ``` --- ## 🔗 Links - **GitHub Repository:** https://github.com/neverinfamous/mysql-mcp - **Docker Hub:** https://hub.docker.com/r/writenotenow/mysql-mcp - **NPM Package:** https://www.npmjs.com/package/@neverinfamous/mysql-mcp - **Changelog:** https://github.com/neverinfamous/mysql-mcp/blob/master/CHANGELOG.md - **Wiki:** https://github.com/neverinfamous/mysql-mcp/wiki - **Issues:** https://github.com/neverinfamous/mysql-mcp/issues - **License:** MIT --- **Full Changelog:** [v2.2.0...v2.3.0](https://github.com/neverinfamous/mysql-mcp/compare/v2.2.0...v2.3.0)