MySQL MCP Server

# mysql-mcp v2.2.0 Release Notes **Release Date:** February 8, 2026 **Status:** Production/Stable --- ## 🎉 Release Highlights **mysql-mcp v2.2.0** is a comprehensive stabilization and hardening release. Every tool group now implements the **P154 Object Existence Verification** pattern, returning structured `{ exists: false }` responses instead of raw MySQL errors. Combined with universal graceful error handling, payload optimization, SQL injection hardening, and 20+ new server instruction sections, this release transforms the developer and AI-agent experience. ### At a Glance - **~120 Bug Fixes** — P154 existence checks across all 23+ tool groups, graceful error handling, payload reductions, response consistency - **~55 Behavioral Changes** — Default limits, payload optimization (P137), tool group migration, Node.js 24 LTS baseline - **~20 New Features** — Summary modes, new tool (`mysql_fulltext_drop`), new parameters, comprehensive ServerInstructions - **6 Security Items** — CVE fixes (hono), SQL injection hardening (5 categories), dependency cleanup - **8 Dependency Bumps** — MCP SDK 1.26.0, mysql2, zod, vitest, and more --- ## 🔒 Security ### SQL Injection Hardening - **Role Tools** — Added `validateIdentifier()` for role names and `validateMySQLUserHost()` for user/host values across all 5 role tool handlers - **Privilege Allowlist** — Added `validateMySQLPrivilege()` with 30+ valid MySQL privilege keywords for GRANT statement validation - **Subquery Detection** — Blocked `(SELECT ...` pattern in WHERE clauses to prevent data exfiltration - **Isolation Level Allowlist** — Explicit allowlist validation for transaction isolation levels - **LIKE Pattern Escaping** — `mysql_role_list` now escapes user-supplied LIKE patterns ### CVE Fixes - **hono Multiple Vulnerabilities** — Fixed JWT algorithm confusion, XSS in ErrorBoundary, Web Cache Deception, IPv4 validation bypass, and arbitrary key read in serve static middleware ### Dependency Cleanup - Removed unused `commander`, `cors`, and `@types/cors` to reduce attack surface --- ## 🐛 Bug Fixes (Highlights) ### Universal P154 Existence Checks Every tool group now returns `{ exists: false, table/schema/collection }` for nonexistent objects instead of raw MySQL errors or ambiguous empty arrays: - **Core** — `mysql_describe_table`, `mysql_get_indexes`, `mysql_table_stats`, `mysql_index_recommendation`, `mysql_create_index`, `mysql_force_index` - **Schema** — `mysql_list_views`, `mysql_list_triggers`, `mysql_list_events`, `mysql_list_stored_procedures`, `mysql_list_functions`, `mysql_list_constraints` - **Text** — All 6 text tools - **Fulltext** — All 5 fulltext tools - **JSON** — All 15 table-querying JSON tools - **Stats** — All 8 stats tools - **Spatial** — All 12 spatial tools - **Admin** — `mysql_flush_tables`, `mysql_index_usage`, `mysql_import_data`, `mysql_export_table` - **Performance** — `mysql_explain`, `mysql_explain_analyze`, `mysql_optimizer_trace` - **Events** — `mysql_event_status`, `mysql_event_list` - **Roles** — `mysql_user_roles`, `mysql_role_grants` - **Security** — `mysql_security_user_privileges`, `mysql_security_sensitive_tables` - **Document Store** — `mysql_doc_collection_info`, `mysql_doc_find`, `mysql_doc_list_collections` - **Sys Schema** — `mysql_sys_schema_stats` - **Partitioning** — `mysql_partition_info`, `mysql_binlog_events` - **Shell** — All 8 shell tools - **Cluster** — `mysql_cluster_instances`, `mysql_cluster_topology` - **ProxySQL** — Credential redaction for `password`/`credentials` variables - **Router** — All 9 router tools return `{ available: false, reason }` for unreachable API ### Graceful Error Handling Create/drop operations now return structured `{ success: false, reason }` instead of raw errors: - `mysql_create_table`, `mysql_drop_table`, `mysql_create_schema`, `mysql_drop_schema` - `mysql_create_index`, `mysql_create_view`, `mysql_role_create`, `mysql_role_drop` - `mysql_event_create`, `mysql_event_alter`, `mysql_event_drop` - `mysql_doc_create_collection`, `mysql_doc_drop_collection` - All transaction tools (commit, rollback, savepoints) ### Informative No-Op Messaging When `ifExists`/`ifNotExists` flag prevents an action, tools now return `{ skipped: true, reason }` instead of ambiguous `{ success: true }`: - `mysql_create_schema` / `mysql_drop_schema` - `mysql_create_table` (new) / `mysql_drop_table` (new) - `mysql_role_create` / `mysql_role_drop` - `mysql_event_drop`, `mysql_doc_drop_collection` ### Notable Individual Fixes - **`mysql_create_index` FULLTEXT/SPATIAL SQL** — Fixed invalid `USING FULLTEXT` syntax; now uses correct `CREATE FULLTEXT INDEX` prefix - **Spatial GeoJSON axis order** — Fixed coordinate conversion for SRID 4326 across 7 spatial tools - **JSON auto-quoting** — Bare strings like `"green"` now auto-wrapped as valid JSON - **`mysql_export_table` datetime** — Fixed extra JSON-style quotes wrapping datetime values - **`mysql_transaction_execute` SELECT data** — Fixed missing row data for SELECT statements in atomic transactions - **`mysql_stats_distribution` bucket boundaries** — Fixed string concatenation instead of arithmetic - **`mysql_sys_io_summary` file type** — Fixed wrong column name (`total_write` → `total_written`) --- ## ✨ New Features ### New Tool - **`mysql_fulltext_drop`** — Drop FULLTEXT indexes, providing symmetry with `mysql_fulltext_create` ### Summary Modes Reduce payload size dramatically for status/diagnostic tools: | Tool | Full → Summary | | ----------------------------- | -------------------- | | `mysql_cluster_status` | ~21KB → ~500B | | `mysql_cluster_router_status` | ~12KB → ~300B/router | | `mysql_innodb_status` | ~5KB → ~200B | | `mysql_optimizer_trace` | ~10KB → ~500B | | `proxysql_status` | ~4KB → ~500B | | `proxysql_runtime_status` | ~3KB → ~300B | ### New Parameters - **`mysql_export_table`** — `limit` parameter to cap exported rows - **`mysql_index_usage`** — `limit` parameter (default: 20 → 10) - **`proxysql_global_variables`** — `limit` and `like` filter parameters - **`mysql_spatial_buffer`** — `segments` parameter for buffer polygon approximation - **Text tools** — `where` parameter on `mysql_regexp_match`, `mysql_like_search`, `mysql_soundex` - **Fulltext tools** — `maxLength` parameter to truncate large TEXT values - **`mysql_concat`** — `includeSourceColumns` option for minimal payload - **`mysql_security_user_privileges`** — `summary` mode for condensed privilege info ### Comprehensive Server Instructions Added 15+ new documentation sections to `ServerInstructions.ts`: Core, Transaction, Admin, Performance, Optimization, Monitoring, Replication, Schema, Events, Sys Schema, Stats, Security, ProxySQL, InnoDB Cluster, Shell, Fulltext, Text, Backup, Partitioning, Role Management, Document Store --- ## 📊 Payload Optimization ### Default Limits | Tool | Before | After | | --------------------------- | ---------- | -------- | | `mysql_export_table` | Unbounded | 100 rows | | `mysql_show_status` | ~517 rows | 100 | | `mysql_show_variables` | ~600 rows | 100 | | `mysql_binlog_events` | 100 events | 20 | | `mysql_query_stats` | 20 | 10 | | `mysql_index_usage` | 50 → 20 | 10 | | `mysql_sys_schema_stats` | 50 → 20 | 10 | | `mysql_sys_memory_summary` | 20 | 10 | | `proxysql_global_variables` | 200 | 50 | ### Minimal Payload (P137) - **Fulltext tools** — Return only `id`, searched column(s), and `relevance` - **Text tools** — Return only `id`, target column(s), and computed result - **`mysql_json_contains`/`mysql_json_search`** — Return only relevant columns instead of `SELECT *` - **`mysql_slow_queries`/`mysql_query_stats`** — Digest text truncated to 200 chars --- ## ⚙️ Changed ### Infrastructure - **Node.js 24 LTS Baseline** — Upgraded from Node 20 across Dockerfile, CI, and `package.json` - **Docker Workflow** — Docker publishing now depends on both `quality-gate` and `codeql` jobs - **Dependabot Grouping** — Added groups for vitest, eslint, and types - **`cluster` tool group** — Migrated from `dba-secure` to `ecosystem` shortcut (42 → 32 / 31 → 41 tools) ### Response Improvements - **`mysql_replication_status` / `mysql_slave_status`** — Return `{ configured: false }` instead of empty object - **Cluster payload reduction** — `Configuration` blobs stripped from `mysql_cluster_status` and `mysql_cluster_router_status` full mode - **`mysql_json_diff`** — Enhanced with value-level comparison (`addedKeys`, `removedKeys`, `differences`) - **`mysql_json_insert`** — Returns `{ changed: true/false }` indicator - **`mysql_create_table`** — Boolean defaults auto-converted (`true` → `1`, `false` → `0`) --- ## 📦 Dependencies - `@modelcontextprotocol/sdk` `^1.25.2` → `^1.26.0` - `@types/node` `^25.0.8` → `^25.2.2` - `@vitest/coverage-v8` `^4.0.17` → `^4.0.18` - `globals` `^17.0.0` → `^17.3.0` - `mysql2` `^3.16.0` → `^3.16.3` - `typescript-eslint` `^8.53.0` → `^8.54.0` - `vitest` `^4.0.17` → `^4.0.18` - `zod` `^4.3.5` → `^4.3.6` --- ## 📦 Installation & Upgrade ### Docker (Recommended) ```bash # Latest v2.2.0 docker pull writenotenow/mysql-mcp:v2.2.0 docker pull writenotenow/mysql-mcp:latest # Run with stdio transport docker run -i --rm writenotenow/mysql-mcp:v2.2.0 \ --transport stdio \ --mysql mysql://user:password@host.docker.internal:3306/database ``` ### NPM ```bash npm install -g @neverinfamous/mysql-mcp@2.2.0 ``` ### From Source ```bash git clone https://github.com/neverinfamous/mysql-mcp.git cd mysql-mcp git checkout v2.2.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 - **Issues:** https://github.com/neverinfamous/mysql-mcp/issues - **License:** MIT --- **Full Changelog:** [v2.1.0...v2.2.0](https://github.com/neverinfamous/mysql-mcp/compare/v2.1.0...v2.2.0)