{"_id":"mysql-mcp-toolkit","_rev":"6-5029e427e50abe96a91f5ed9645bf8cf","name":"mysql-mcp-toolkit","dist-tags":{"latest":"1.5.0"},"versions":{"1.1.0":{"name":"mysql-mcp-toolkit","version":"1.1.0","keywords":["mcp","mysql","cursor","modelcontextprotocol","database"],"author":{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"},"license":"MIT","_id":"mysql-mcp-toolkit@1.1.0","maintainers":[{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"}],"homepage":"https://github.com/ogzhncrt/mysql-mcp#readme","bugs":{"url":"https://github.com/ogzhncrt/mysql-mcp/issues"},"bin":{"mcp-server-mysql":"dist/index.js"},"dist":{"shasum":"9ec1ee03c643dce056e1df0693e0e0ca3cd548af","tarball":"https://registry.npmjs.org/mysql-mcp-toolkit/-/mysql-mcp-toolkit-1.1.0.tgz","fileCount":69,"integrity":"sha512-vzH2ikXCM5V1fsTeInV0pPZhwoeI5B6tpuLt1jabSr1zcQcZoBzQPo6x7DqP0Qnd5F2+GDphqEhyWpI0axPYNg==","signatures":[{"sig":"MEYCIQDo2cRwLqZzK0HkssX3rdo5UsQgSlMt8hHVvN0yvjKu4QIhAL13nfXLTbu+ybiCvrMxE7f4ylOuxR1G8nFJQbY2NqG7","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":121439},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"11db2ba4df7a28b9605d89034467a651f771dc21","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"},"repository":{"url":"git+https://github.com/ogzhncrt/mysql-mcp.git","type":"git"},"_npmVersion":"11.13.0","description":"MCP server for MySQL — connect Cursor (and other MCP clients) to your databases via config file or env vars","directories":{},"_nodeVersion":"22.13.1","dependencies":{"zod":"^3.23.0","mysql2":"^3.11.5","@modelcontextprotocol/sdk":"^1.0.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.16.1","vitest":"^2.0.0","typescript":"^5.5.3","@types/node":"^20.14.10"},"_npmOperationalInternal":{"tmp":"tmp/mysql-mcp-toolkit_1.1.0_1780392138517_0.009176222389653876","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"mysql-mcp-toolkit","version":"1.2.0","keywords":["mcp","mysql","cursor","modelcontextprotocol","database"],"author":{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"},"license":"MIT","_id":"mysql-mcp-toolkit@1.2.0","maintainers":[{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"}],"homepage":"https://github.com/ogzhncrt/mysql-mcp#readme","bugs":{"url":"https://github.com/ogzhncrt/mysql-mcp/issues"},"bin":{"mcp-server-mysql":"dist/index.js"},"dist":{"shasum":"b4e950c0eb2b31ff75e9f272a1854197eddf5a03","tarball":"https://registry.npmjs.org/mysql-mcp-toolkit/-/mysql-mcp-toolkit-1.2.0.tgz","fileCount":51,"integrity":"sha512-DPPdAbo1kgoBsdhUJALB1zmY+LnU+0F1y2PFuJf9d+2qgPVI7wfATj/XuH2tx7cGEY5O6jVQsYaNHUPCtL9Svg==","signatures":[{"sig":"MEUCIFXSO7/dmN5HHL0Qv9ayHO2hASaaYSJBaap0UbwZEcIzAiEA8s9Wn7QsWey5cLa3GzGQOUXk5fmy5crCBbma4GdJ2ME=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":90292},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"dae5a62a57f1cb75c60d3e695d0fd2885b14473a","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"},"repository":{"url":"git+https://github.com/ogzhncrt/mysql-mcp.git","type":"git"},"_npmVersion":"11.13.0","description":"MCP server for MySQL — connect Cursor (and other MCP clients) to your databases via config file or env vars","directories":{},"_nodeVersion":"22.13.1","dependencies":{"zod":"^3.23.0","mysql2":"^3.11.5","@modelcontextprotocol/sdk":"^1.0.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.16.1","vitest":"^2.0.0","typescript":"^5.5.3","@types/node":"^20.14.10"},"_npmOperationalInternal":{"tmp":"tmp/mysql-mcp-toolkit_1.2.0_1780492721534_0.9373337705489033","host":"s3://npm-registry-packages-npm-production"}},"1.3.0":{"name":"mysql-mcp-toolkit","version":"1.3.0","keywords":["mcp","mysql","cursor","modelcontextprotocol","database"],"author":{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"},"license":"MIT","_id":"mysql-mcp-toolkit@1.3.0","maintainers":[{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"}],"homepage":"https://github.com/ogzhncrt/mysql-mcp#readme","bugs":{"url":"https://github.com/ogzhncrt/mysql-mcp/issues"},"bin":{"mcp-server-mysql":"dist/index.js"},"dist":{"shasum":"2cdf1f7c609d5eb67050a4ea982707ddec30915b","tarball":"https://registry.npmjs.org/mysql-mcp-toolkit/-/mysql-mcp-toolkit-1.3.0.tgz","fileCount":57,"integrity":"sha512-1cxhuTtBZMJbF+wMbtpTmKkPbJhFl5eWTm3YQ2HOErdOei2m7T7+0JSfK9wk4hbrJCBXQa1pYL04P6mvsIByFw==","signatures":[{"sig":"MEUCIGBW6QqKRh8ouUz99VGhEmTniSp8VDe7NPz4Pq1lMh7tAiEAwUESWAXKKGYR1iCndxUVHUvIg1B+PUPL5ynTrLvs6HI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":123308},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"43368b02d94907526096c66d190cb0fc5e00f084","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"},"repository":{"url":"git+https://github.com/ogzhncrt/mysql-mcp.git","type":"git"},"_npmVersion":"11.13.0","description":"MCP server for MySQL — connect Cursor (and other MCP clients) to your databases via config file or env vars","directories":{},"_nodeVersion":"22.13.1","dependencies":{"zod":"^3.23.0","mysql2":"^3.11.5","@modelcontextprotocol/sdk":"^1.0.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.16.1","vitest":"^2.0.0","typescript":"^5.5.3","@types/node":"^20.14.10"},"_npmOperationalInternal":{"tmp":"tmp/mysql-mcp-toolkit_1.3.0_1781263907750_0.17292557058557456","host":"s3://npm-registry-packages-npm-production"}},"1.3.1":{"name":"mysql-mcp-toolkit","version":"1.3.1","keywords":["mcp","mysql","cursor","modelcontextprotocol","database"],"author":{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"},"license":"MIT","_id":"mysql-mcp-toolkit@1.3.1","maintainers":[{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"}],"homepage":"https://github.com/ogzhncrt/mysql-mcp#readme","bugs":{"url":"https://github.com/ogzhncrt/mysql-mcp/issues"},"bin":{"mcp-server-mysql":"dist/index.js"},"dist":{"shasum":"e8dd3728d1db43a5986210171f5e95668ae19877","tarball":"https://registry.npmjs.org/mysql-mcp-toolkit/-/mysql-mcp-toolkit-1.3.1.tgz","fileCount":57,"integrity":"sha512-zCRAQ+TyXDm8CmHBpcyisBUyDicmJxuVyEhTMdYOwmDxvjCfAILiouq//G3lyMLfyfX20I+G2FoXgF6rkmOYSQ==","signatures":[{"sig":"MEQCICS3IlzsijOyEZnGZNPCwPWCq6u8pL8fiKzDy6ybjDkaAiBcHIlGln1u1BTB5MrUot5rWbpMbfiFijF1Q1IYW1tBAw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":129096},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"2bb046852b4b010483240b348dc83fe5bf0d5b93","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"},"repository":{"url":"git+https://github.com/ogzhncrt/mysql-mcp.git","type":"git"},"_npmVersion":"11.13.0","description":"MCP server for MySQL — connect Cursor (and other MCP clients) to your databases via config file or env vars","directories":{},"_nodeVersion":"22.13.1","dependencies":{"zod":"^3.23.0","mysql2":"^3.11.5","@modelcontextprotocol/sdk":"^1.0.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.16.1","vitest":"^2.0.0","typescript":"^5.5.3","@types/node":"^20.14.10"},"_npmOperationalInternal":{"tmp":"tmp/mysql-mcp-toolkit_1.3.1_1782309711184_0.13507272084455968","host":"s3://npm-registry-packages-npm-production"}},"1.4.0":{"name":"mysql-mcp-toolkit","version":"1.4.0","keywords":["mcp","mysql","cursor","modelcontextprotocol","database"],"author":{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"},"license":"MIT","_id":"mysql-mcp-toolkit@1.4.0","maintainers":[{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"}],"homepage":"https://github.com/ogzhncrt/mysql-mcp#readme","bugs":{"url":"https://github.com/ogzhncrt/mysql-mcp/issues"},"bin":{"mcp-server-mysql":"dist/index.js"},"dist":{"shasum":"9dac8cf65661f8d2123b0380ef4b43aa1db67cd4","tarball":"https://registry.npmjs.org/mysql-mcp-toolkit/-/mysql-mcp-toolkit-1.4.0.tgz","fileCount":59,"integrity":"sha512-LEjfYv0VkvBVOdFGA+lY4aYYFQkSZrdEP9/zY0T8mA79XtC+j32QvH7jtjAsrUxpd9nkgW5u2g8SewStD4jjTw==","signatures":[{"sig":"MEQCIED6zJ8QkX9dmdnd1BbZfmaAC8jUhgm1odOFdZ/F0QT4AiA1yiBtnUFHblBPxkz3ywJWUBD5wghjsUaeztQnWGmIvg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":140836},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"142ed5c28d4f875a6745e55d8e0d24968a172556","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"},"repository":{"url":"git+https://github.com/ogzhncrt/mysql-mcp.git","type":"git"},"_npmVersion":"11.13.0","description":"MCP server for MySQL: connect Cursor (and other MCP clients) to your databases via config file or env vars","directories":{},"_nodeVersion":"22.13.1","dependencies":{"zod":"^3.23.0","mysql2":"^3.11.5","@modelcontextprotocol/sdk":"^1.0.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.16.1","vitest":"^2.0.0","typescript":"^5.5.3","@types/node":"^20.14.10"},"_npmOperationalInternal":{"tmp":"tmp/mysql-mcp-toolkit_1.4.0_1782310821452_0.5302653645042752","host":"s3://npm-registry-packages-npm-production"}},"1.5.0":{"name":"mysql-mcp-toolkit","version":"1.5.0","description":"MCP server for MySQL: connect Cursor (and other MCP clients) to your databases via config file or env vars","author":{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"},"repository":{"type":"git","url":"git+https://github.com/ogzhncrt/mysql-mcp.git"},"homepage":"https://github.com/ogzhncrt/mysql-mcp#readme","bugs":{"url":"https://github.com/ogzhncrt/mysql-mcp/issues"},"publishConfig":{"access":"public"},"type":"module","main":"dist/index.js","bin":{"mcp-server-mysql":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsx src/index.ts","test":"vitest run","prepublishOnly":"npm run build"},"keywords":["mcp","mysql","cursor","modelcontextprotocol","database"],"license":"MIT","engines":{"node":">=18"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.4","mysql2":"^3.11.5","zod":"^3.23.0"},"devDependencies":{"@types/node":"^20.14.10","tsx":"^4.16.1","typescript":"^5.5.3","vitest":"^2.0.0"},"gitHead":"1cdaf23ca7f3773a3dab8ad93d6e501adc6a9ce4","types":"./dist/index.d.ts","_id":"mysql-mcp-toolkit@1.5.0","_nodeVersion":"22.13.1","_npmVersion":"11.13.0","dist":{"integrity":"sha512-VBs1yXzs4igVsDrCWhuP6v3l2lHak3gSFEcUqn+xqoIXvzi+PRQdVHbMjvbdPijg8N/+vkaPxDOeaGnKnSS1FA==","shasum":"cb0c42085d699d19e2237f807106ada91dfa7e9a","tarball":"https://registry.npmjs.org/mysql-mcp-toolkit/-/mysql-mcp-toolkit-1.5.0.tgz","fileCount":67,"unpackedSize":171128,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIG4UrdJgvDvh4oMkY7v7qN6gVM4nJkuSSc45NqD5zzP2AiAUGc+tzDiXYXpnquLkydRsV6q8fmdQ1mkQvI1KgUJx7g=="}]},"_npmUser":{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"},"directories":{},"maintainers":[{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mysql-mcp-toolkit_1.5.0_1786354630318_0.8052320220400899"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-02T09:22:18.344Z","modified":"2026-08-10T09:37:10.616Z","1.1.0":"2026-06-02T09:22:18.664Z","1.2.0":"2026-06-03T13:18:41.683Z","1.3.0":"2026-06-12T11:31:47.891Z","1.3.1":"2026-06-24T14:01:51.304Z","1.4.0":"2026-06-24T14:20:21.600Z","1.5.0":"2026-08-10T09:37:10.459Z"},"bugs":{"url":"https://github.com/ogzhncrt/mysql-mcp/issues"},"author":{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"},"license":"MIT","homepage":"https://github.com/ogzhncrt/mysql-mcp#readme","keywords":["mcp","mysql","cursor","modelcontextprotocol","database"],"repository":{"type":"git","url":"git+https://github.com/ogzhncrt/mysql-mcp.git"},"description":"MCP server for MySQL: connect Cursor (and other MCP clients) to your databases via config file or env vars","maintainers":[{"name":"oguzhancerit","email":"ogzhncrt@gmail.com"}],"readme":"# mcp-server-mysql\n\n[![npm](https://img.shields.io/npm/v/mysql-mcp-toolkit.svg)](https://www.npmjs.com/package/mysql-mcp-toolkit)\n\nA Model Context Protocol (MCP) server for MySQL. Lets Cursor and other MCP\nclients list tables, describe schema, and run SQL against any MySQL database\nyou configure, over stdio, with read-only protection for production\nconnections.\n\nPublished as **`mysql-mcp-toolkit`** on npm.\n\n## Quick start (config file)\n\n1. Generate a starter config:\n   ```bash\n   npx -y mysql-mcp-toolkit init\n   # writes ~/.config/mcp-server-mysql/config.json\n   ```\n2. Replace the placeholder credentials in that file. Any field still\n   containing `your-` is treated as a placeholder and the connection is\n   rejected at startup.\n3. Add the server to Cursor's `~/.cursor/mcp.json`:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"mysql\": {\n         \"command\": \"npx\",\n         \"args\": [\n           \"-y\",\n           \"mysql-mcp-toolkit@latest\",\n           \"--config\",\n           \"/absolute/path/to/config.json\"\n         ]\n       }\n     }\n   }\n   ```\n\n   The `@latest` tag matters; see [Updating](#updating). Without it, npx\n   caches the first version it installs and keeps reusing it.\n\n4. Restart Cursor. You should see `mysql` show up under MCP tools.\n\n## Quick start (env vars only)\n\nIf you only need one connection, skip the config file entirely:\n\n```json\n{\n  \"mcpServers\": {\n    \"mysql\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mysql-mcp-toolkit@latest\"],\n      \"env\": {\n        \"MYSQL_HOST\": \"127.0.0.1\",\n        \"MYSQL_PORT\": \"3306\",\n        \"MYSQL_USER\": \"root\",\n        \"MYSQL_PASSWORD\": \"secret\",\n        \"MYSQL_DATABASE\": \"myapp\",\n        \"MYSQL_READ_ONLY\": \"true\"\n      }\n    }\n  }\n}\n```\n\nOr supply a single connection URL instead of the four discrete variables:\n\n```json\n{\n  \"mcpServers\": {\n    \"mysql\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mysql-mcp-toolkit@latest\"],\n      \"env\": {\n        \"MYSQL_URL\": \"mysql://root:secret@127.0.0.1:3306/myapp\",\n        \"MYSQL_READ_ONLY\": \"true\"\n      }\n    }\n  }\n}\n```\n\nUser, password, and database in the URL are URL-decoded, so reserved\ncharacters (e.g. `@` or `/` in a password) can be percent-encoded. Add\n`?ssl=true|false|amazon-rds` or use the `mysqls://` scheme to enable TLS\n(`MYSQL_SSL` still overrides). `MYSQL_CONNECTION_NAME`, `MYSQL_READ_ONLY`,\nand `MYSQL_QUERY_TIMEOUT_MS` apply to either form.\n\n## Updating\n\n`npx` caches each package spec under `~/.npm/_npx/<hash>/`. If your `mcp.json`\npoints at `mysql-mcp-toolkit` with no version tag, npx installs whatever is\ncurrent on the first run and **keeps reusing that cached copy forever**,\neven after new versions ship to npm. That's why the examples above pin\n`@latest`: it forces npx to resolve against the registry on every spawn, so\nnew releases get picked up the next time Cursor restarts the server.\n\n| You want…                            | Use this in `mcp.json`              | Update behavior                          |\n| ------------------------------------ | ----------------------------------- | ---------------------------------------- |\n| Always run the newest release        | `mysql-mcp-toolkit@latest`          | Auto-updates on Cursor restart           |\n| Reproducible pin to a known version  | `mysql-mcp-toolkit@1.2.0`           | Manual: edit `mcp.json` on each upgrade |\n| Force-refresh an unpinned cache once | `mysql-mcp-toolkit` (no tag)        | `rm -rf ~/.npm/_npx` before restart      |\n\nAfter any of these, **restart Cursor** to respawn the MCP child process.\nVerify the upgrade worked by checking the tool list: `table_stats`,\n`list_foreign_keys`, and `search_columns` arrived in 1.3.0, so seeing them\nin Cursor's MCP panel confirms you're current.\n\n## Tools\n\n| Tool                | What it does                                                                                                                                                                                                                                                                            |\n| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `execute_query`     | Run any SQL. Supports `params` for `?` placeholders, `format: objects\\|compact`, and `maxResponseBytes` truncation. Bare `SELECT`s and `WITH … SELECT` CTEs get an auto `LIMIT` (max 10,000) and a `MAX_EXECUTION_TIME` optimizer hint so `timeoutMs` cancels the query **server-side** on MySQL 5.7.4+.           |\n| `explain_query`     | `EXPLAIN` a statement without executing it. Supports `format: TRADITIONAL\\|JSON\\|TREE` and `params`. Safe on read-only connections. Rejects `EXPLAIN ANALYZE` (which executes) and multi-statement input.                                                                                |\n| `list_tables`       | `SHOW TABLES` on the chosen connection.                                                                                                                                                                                                                                                  |\n| `describe_table`    | `DESCRIBE <table>` + `SHOW INDEXES FROM <table>`. Identifier must be 1-64 chars and contain no backticks or control characters (dollar signs, hyphens, and unicode letters are fine).                                                                                                    |\n| `show_create_table` | Returns the full `CREATE TABLE` statement: column types, defaults, indexes, foreign keys, engine, charset. Also works on views (returns `CREATE VIEW`).                                                                                                                                 |\n| `get_schema`        | One-call map of the whole database: every table and view with its columns (name, type, nullability, key) and foreign keys. Scope with `tables`, or pass `includeColumns: false` for a relationship-only overview on large schemas. Output is capped by `maxResponseBytes`.               |\n| `table_stats`       | Per-table size and row statistics from `information_schema.TABLES`: approximate row count, data/index bytes, engine, collation, auto-increment. Optional `table` filter; sorted largest-first.                                                                                           |\n| `list_foreign_keys` | Foreign key relationships in the database, grouped per constraint (multi-column keys included), with update/delete rules. Pass `table` to get both directions: FKs on the table and FKs referencing it.                                                                                 |\n| `search_columns`    | Find columns by name across every table (case-insensitive substring, max 500 matches). Returns table, type, nullability, and key info.                                                                                                                                                   |\n| `sample_rows`       | Preview a few rows from a table (`SELECT * … LIMIT n`, default 10, max 1000) to see real data shape without hand-writing SQL. Read-only-safe.                                                                                                                                            |\n| `list_databases`    | Lists configured connections (host, database, port, read-only flag, ssl flag). Never includes passwords.                                                                                                                                                                                |\n| `list_schemas`      | `SHOW DATABASES` — the schemas visible to the connection's user. Use a returned name as the `database` argument to the schema tools to inspect another schema on the same server.                                                                                                        |\n| `server_info`       | Read-only diagnostics: server version, curated global variables, key status counters, and (by default) the current process list (`SHOW FULL PROCESSLIST`).                                                                                                                              |\n\nEvery schema tool (`list_tables`, `describe_table`, `show_create_table`,\n`get_schema`, `table_stats`, `list_foreign_keys`, `search_columns`,\n`sample_rows`) accepts an optional `database` argument to inspect a schema\nother than the one the connection is attached to. Use `list_schemas` to\ndiscover the available names.\n\nAll tools advertise [MCP tool annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations)\n(`readOnlyHint`, `destructiveHint`, `idempotentHint`), so clients can relax\napproval prompts for the safe ones.\n\n### Read-only enforcement\n\nConnections with `readOnly: true` use a **default-deny allowlist**: only\nstatements starting with `SELECT`, `WITH`, `TABLE`, `VALUES`, `SHOW`,\n`EXPLAIN`, `DESCRIBE`/`DESC`, `HELP`, or `CHECKSUM` are accepted, and\n`SELECT`/`WITH` bodies are additionally scanned for embedded writes (CTE\nwrites like `WITH x AS (...) DELETE FROM t`, `INTO OUTFILE`/`DUMPFILE`,\n`FOR UPDATE` locks). Everything else, including `LOAD DATA`, `SET`,\n`KILL`, `FLUSH`, `EXPLAIN ANALYZE` (which executes), and transaction\ncontrol, is rejected before any SQL leaves the process. Detection is\ncomment-, string-literal-, and backtick-identifier-aware, so neither\n`/* DELETE */` comments nor a column named `` `update` `` confuse it.\nMySQL *executable* comments (`/*! ... */`, `/*!50000 ... */`), whose\ncontents the server actually runs, are inspected rather than ignored, and\n`--` is only treated as a comment when followed by whitespace — so\n`/*! DELETE FROM t */` and `SELECT 1--1;DELETE FROM t` are both rejected.\n\nEach tool accepts an optional `connection` argument. If omitted, the default\nfrom `defaults.connection` (or the literal `\"default\"`) is used. Tools that\nrun user-supplied SQL also accept an optional `timeoutMs` (defaults to the\nconnection's `queryTimeoutMs`, then `defaults.queryTimeoutMs`, then `30000`).\nOn SELECT, the timeout is enforced server-side via MySQL's\n`MAX_EXECUTION_TIME` optimizer hint. On non-SELECT statements the timeout\nonly closes the client socket; the server may keep the query running.\n\n### Parameterized queries\n\n```jsonc\n// execute_query\n{\n  \"query\": \"SELECT id, email FROM users WHERE org_id = ? AND active = ?\",\n  \"params\": [42, true]\n}\n```\n\nDriver-side escaping prevents SQL injection. Always prefer this over\ninterpolating values into the `query` string.\n\n### Large result sets\n\n`execute_query` accepts two options that keep responses small enough for\nan agent's context window:\n\n- `format: \"compact\"` returns `{ columns: [...], rows: [[...]] }` instead\n  of one JSON object per row, much smaller for wide tables.\n- `maxResponseBytes` (default `1000000`, configurable via\n  `defaults.maxResponseBytes`) caps the serialized size of returned rows.\n  When exceeded, rows are truncated and the response includes\n  `truncated: true`, the fetched row count, and a note.\n- `offset` paginates a bare `SELECT` / `WITH…SELECT` that has no explicit\n  `LIMIT`: the server appends `LIMIT n OFFSET m`. Combine with `limit` to\n  page through a large result set. Ignored when the query already has a\n  `LIMIT`.\n\n### Session state\n\nEach tool call may run on a different pooled connection. Transactions\n(`BEGIN`/`COMMIT`), `SET` statements, `USE`, and temporary tables therefore\ndo **not** carry over between calls; don't try to span a transaction\nacross multiple `execute_query` invocations.\n\n`BIGINT` values above 2^53 are returned as strings to avoid silent\nprecision loss, and `DATE`/`DATETIME`/`TIMESTAMP` columns are returned as\nplain strings (no timezone conversion).\n\n## Resources\n\nFor each configured connection the server exposes a resource:\n\n- URI: `database://<connectionName>`\n- MIME type: `application/json`\n- Body: `{ connectionName, host, database, port, readOnly }` (no password)\n\n## Config file reference\n\n```json\n{\n  \"defaults\": {\n    \"connection\": \"default\",\n    \"queryLimit\": 100,\n    \"queryTimeoutMs\": 30000,\n    \"maxResponseBytes\": 1000000\n  },\n  \"connections\": [\n    {\n      \"connectionName\": \"default\",\n      \"host\": \"127.0.0.1\",\n      \"port\": 3306,\n      \"user\": \"root\",\n      \"password\": \"secret\",\n      \"database\": \"myapp\",\n      \"readOnly\": false,\n      \"connectionLimit\": 5,\n      \"queueLimit\": 20\n    },\n    {\n      \"connectionName\": \"production\",\n      \"host\": \"db.example.com\",\n      \"port\": 3306,\n      \"user\": \"readonly_user\",\n      \"password\": \"prod-secret\",\n      \"database\": \"myapp\",\n      \"readOnly\": true,\n      \"ssl\": \"Amazon RDS\",\n      \"queryTimeoutMs\": 15000\n    }\n  ]\n}\n```\n\n| Field                          | Required | Default      | Notes                                              |\n| ------------------------------ | -------- | ------------ | -------------------------------------------------- |\n| `defaults.connection`           | no       | `\"default\"`  | Must match a configured `connectionName`.          |\n| `defaults.queryLimit`           | no       | `100`        | Used when a bare `SELECT` has no top-level `LIMIT`. Hard max `10000` (enforced). |\n| `defaults.queryTimeoutMs`       | no       | `30000`      | Per-query timeout in milliseconds.                 |\n| `defaults.maxResponseBytes`     | no       | `1000000`    | Cap on serialized row bytes per response; rows beyond it are truncated with a notice. Min `1024`. |\n| `connections[].connectionName`  | yes      | -            | Unique, `^[a-zA-Z0-9_-]+$`.                        |\n| `connections[].host`            | yes      | -            |                                                    |\n| `connections[].port`            | no       | `3306`       | Integer 1-65535.                                   |\n| `connections[].user`            | yes      | -            |                                                    |\n| `connections[].password`        | yes      | -            |                                                    |\n| `connections[].database`        | yes      | -            |                                                    |\n| `connections[].readOnly`        | no       | `false`      | When `true`, only read statements run. See [Read-only enforcement](#read-only-enforcement). |\n| `connections[].connectionLimit` | no       | `5`          | Max connections per pool.                          |\n| `connections[].queueLimit`      | no       | `20`         | Max queued requests once the pool is saturated; `0` means unbounded. |\n| `connections[].queryTimeoutMs`  | no       | inherits `defaults.queryTimeoutMs` | Per-connection timeout override. Capped at 1 hour. |\n| `connections[].ssl`             | no       | unset        | `true` / `false` / `\"Amazon RDS\"` / mysql2 SSL object (`{ ca, cert, key, rejectUnauthorized, ... }`). |\n| `connections[].multipleStatements` | no    | `false`      | When `true`, allows multiple `;`-separated statements per query. Enables a class of SQL injection, so leave off unless you know you need it. |\n\n### Config resolution order\n\nThe first source that exists wins:\n\n1. `--config <path>` flag\n2. `MCP_MYSQL_CONFIG` environment variable\n3. `./mcp-mysql.config.json` (current working directory)\n4. `~/.config/mcp-server-mysql/config.json`\n5. `MYSQL_*` environment variables (single connection)\n\n### Environment variables (only when no config file is found)\n\n| Variable                | Required | Default      |\n| ----------------------- | -------- | ------------ |\n| `MYSQL_URL`             | no       | unset (`mysql://user:pass@host:port/db`; an alternative to the four vars below) |\n| `MYSQL_HOST`            | yes (if no URL) | -     |\n| `MYSQL_USER`            | yes (if no URL) | -     |\n| `MYSQL_PASSWORD`        | yes (if no URL) | -     |\n| `MYSQL_DATABASE`        | yes (if no URL) | -     |\n| `MYSQL_PORT`            | no       | `3306`       |\n| `MYSQL_CONNECTION_NAME` | no       | `default`    |\n| `MYSQL_READ_ONLY`       | no       | `false` (true when value is `true` or `1`) |\n| `MYSQL_SSL`             | no       | unset (`true` / `false` / `amazon-rds`) |\n| `MYSQL_QUERY_TIMEOUT_MS`| no       | `30000`      |\n\n## `mcp-server-mysql init`\n\n```\nnpx -y mysql-mcp-toolkit init [--output <path>]\n```\n\nCopies the bundled `config.example.json` to the target path. Default target\nis `~/.config/mcp-server-mysql/config.json`. The command refuses to\noverwrite an existing file. Pick a different `--output` or delete the\ntarget first.\n\n## `--check`\n\nValidate config and connectivity without starting the MCP server:\n\n```\nnpx -y mysql-mcp-toolkit --check [--config <path>]\n```\n\nLoads config, pings every connection with `SELECT 1`, prints a per-\nconnection status report to stderr, and exits non-zero if any connection\nfails. Useful before wiring the server into an MCP client.\n\n## Security\n\n- Never commit your config file. The included `.gitignore` excludes\n  `mcp-mysql.config.json` and `config.json` at the repo root.\n- Set `readOnly: true` for any connection that points at a shared or\n  production database. The server enforces this at the tool layer\n  before any SQL leaves the process.\n- If a password leaks into git history or logs, rotate it.\n- `list_databases` and `database://` resources never include passwords.\n- All MCP server logging goes to **stderr**; stdout is reserved for the\n  protocol.\n\n## Development\n\n```bash\nnpm install\nnpm run dev -- --config ./config.example.json   # expect a placeholder error\nnpm test\nnpm run build\n```\n\n## Publishing\n\nFor maintainers only:\n\n```bash\nnpm run build\nnpm test\nnpm publish        # access defaults to public via publishConfig\n```\n\nThe `prepublishOnly` script runs `npm run build` automatically. Bump the\nversion in `package.json` and add a `CHANGELOG.md` entry before publishing.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}