MySQL MCP Server

# mysql-mcp v2.1.0 Release Notes **Release Date:** January 3, 2026 **Status:** Production/Stable --- ## 🎉 Release Highlights **mysql-mcp v2.1.0** delivers significant bug fixes, performance improvements, and enhanced testing coverage. This release focuses on production stability with fixes for Document Store, Group Replication, InnoDB Cluster, spatial tools, and MySQL Shell integration. ### At a Glance - **12+ Bug Fixes** — Document Store filters, Group Replication MySQL 8.0 compatibility, spatial coordinate handling, Router TLS, and more - **Performance Improvements** — Native MCP SDK logging, parallelized health queries, batched index queries (N+1 → 1), configurable metadata cache - **112 New Tests** — Branch coverage improved from ~83% to ~86% (1590 tests total) - **New Parameters** — `updateServerSettings`, `ddlOnly`, and `all` for shell/backup tools --- ## 🐛 Bug Fixes ### Document Store - **Document Store Filter Tools** — Fixed `mysql_doc_modify` and `mysql_doc_remove` failing with "Invalid JSON path expression" error. Added `parseDocFilter()` function supporting three filter formats: - By `_id`: Direct 32-char hex string (e.g., `bbc83181703d43e68ffad119c4bbbfde`) - By `field=value`: Simple equality (e.g., `name=Alice`, `age=30`) - By JSON path existence: Path starting with `$` (e.g., `$.address`) - Now uses parameterized queries for SQL injection protection ### Group Replication & InnoDB Cluster - **Group Replication Tools MySQL 8.0 Compatibility** — Fixed `mysql_gr_members` and `mysql_gr_transactions` failing with "Unknown column" errors on MySQL 8.0.44. Removed non-existent columns from queries. - **InnoDB Cluster Status Tool** — Fixed `mysql_cluster_status` failing with "Unable to query cluster metadata" due to hardcoded column names. Changed to `SELECT *` for compatibility across MySQL versions. ### Spatial Tools - **Spatial Coordinate Order (Final Fix)** — Fixed `mysql_spatial_point`, `mysql_spatial_distance`, and `mysql_spatial_distance_sphere` to correctly accept longitude-latitude parameter order by using MySQL's `axis-order=long-lat` option. ### MySQL Router - **Router TLS with Node.js fetch** — Fixed `mysql_router_*` tools failing with "fetch failed" when `MYSQL_ROUTER_INSECURE=true`. Replaced with native `https.request()` module for proper self-signed certificate handling. ### Partitioning - **Partitioning Tools** — Fixed `mysql_reorganize_partition` to support both RANGE and LIST partition types (previously hardcoded to RANGE only). Added required `partitionType` parameter to schema. ### MySQL Shell - **MySQL Shell Tools Error Handling** — Improved error detection in `execShellJS()` to properly catch errors from stderr (e.g., `local_infile disabled`, privilege errors, fatal dump errors). - **MySQL Shell Export Table** — Removed unsupported `columns` option from `mysqlsh_export_table` (not supported by `util.exportTable()` in MySQL Shell 9.x). --- ## ✨ New Features ### New Tool Parameters - **`mysqlsh_import_table` / `mysqlsh_load_dump`** — Added `updateServerSettings` boolean option to automatically enable `local_infile` on the server before import/load operations - **`mysqlsh_dump_schemas`** — Added `ddlOnly` boolean option to dump only DDL (schema structure) without events, triggers, or routines - **`mysqlsh_dump_tables`** — Added `all` boolean option to control whether triggers are included in the dump ### Server Instructions - **Automatic Usage Instructions** — Usage instructions are now automatically provided to AI agents via the MCP protocol's `instructions` capability during server initialization --- ## ⚡ Performance Improvements | Improvement | Description | |------------|-------------| | **Native MCP Logging** | Upgraded to MCP SDK v1.25.1 with native `server.sendLoggingMessage()` | | **Parallelized Health Queries** | Health resource now executes status and max_connections queries concurrently using `Promise.all()` | | **Batched Index Queries** | `SchemaManager.getSchema()` now fetches all indexes in a single query (eliminates N+1 pattern) | | **Metadata Cache with TTL** | Added configurable TTL-based cache (default 30s, via `METADATA_CACHE_TTL_MS`) | --- ## 🧪 Testing Improvements - **112 New Tests** targeting uncovered branches across multiple modules: - **CLI** — `canSkipMySQLConnection()` covering router-only, proxysql-only, shell-only, ecosystem shortcuts - **Shell Types** — 100% branch coverage for `booleanCoerce` preprocessor - **Data Transfer** — Tests for `updateServerSettings`, `local_infile` error handling, X Protocol - **Backup/Restore** — Tests for `ddlOnly` mode, privilege errors, fatal dump errors - **JSON Enhanced** — Tests for merge, diff, type mappings, cardinality filtering - **InnoDB Cluster** — New test file covering fallback to GR status, error handling - **Branch Coverage** — Improved from ~83% to ~86% - **Total Tests** — 1590 tests passing across 101 test files --- ## 🗑️ Removed - **Jupyter Quickstart Notebook** — Removed `examples/notebooks/quickstart.ipynb` and the `examples/` directory due to kernel instability issues on Windows. Usage instructions are now provided via MCP protocol. --- ## 📝 Changed - **Server Instructions** — Added document store filter syntax documentation with examples. Added spatial tools section documenting coordinate order behavior. - **Partitioning Schema Descriptions** — Improved `value` parameter descriptions to clarify only boundary values should be provided. - **Logger Tests** — Updated to match RFC 5424 severity levels (`warn` → `warning`). --- ## 📦 Installation & Upgrade ### Docker (Recommended) ```bash # Latest v2.1.0 docker pull writenotenow/mysql-mcp:v2.1.0 docker pull writenotenow/mysql-mcp:latest # Run with stdio transport docker run -i --rm writenotenow/mysql-mcp:v2.1.0 \ --transport stdio \ --mysql mysql://user:password@host.docker.internal:3306/database ``` ### NPM ```bash npm install -g mysql-mcp@2.1.0 ``` ### From Source ```bash git clone https://github.com/neverinfamous/mysql-mcp.git cd mysql-mcp git checkout v2.1.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/mysql-mcp - **Changelog:** https://github.com/neverinfamous/mysql-mcp/blob/master/CHANGELOG.md - **Issues:** https://github.com/neverinfamous/mysql-mcp/issues - **License:** MIT --- **Full Changelog:** [v2.0.0...v2.1.0](https://github.com/neverinfamous/mysql-mcp/compare/v2.0.0...v2.1.0)