{"_id":"@abelmferreira/mcp-mysql","_rev":"4-f870ba72d6c91c1f3fc6f44f63c409c4","name":"@abelmferreira/mcp-mysql","dist-tags":{"latest":"1.0.2"},"versions":{"0.0.0-stage":{"name":"@abelmferreira/mcp-mysql","version":"0.0.0-stage","_id":"@abelmferreira/mcp-mysql@0.0.0-stage","stub":true,"maintainers":[{"name":"abelmferreira","email":"abelmferreira@gmail.com"}],"dist":{"shasum":"4408a4eeb4baa3105ea9e1a4b54da2cbeb29df8c","tarball":"https://registry.npmjs.org/@abelmferreira/mcp-mysql/-/mcp-mysql-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-t6YCDaHAaz97o0GfoKKyI+7t2K0Y/JUn16JHlks2HBMNEorb+8ARIjyQdBETnrNr7J/ZpnHl4idzBzRfDhsA+w==","signatures":[{"sig":"MEUCIQCA09KhMJ9SJ2dZEiabcyqWlGZFR43dREB6RYUgu0+2JgIgd6RPr9wLBFZrQMP+3V2cslWx9RdvniWk7FhuTtGYy1E=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":346},"_npmUser":{"name":"abelmferreira","email":"abelmferreira@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"1.0.0":{"name":"@abelmferreira/mcp-mysql","version":"1.0.0","keywords":["anthropic","claude","claude-code","database","mariadb","mcp","mcp-server","model-context-protocol","mysql","read-only","sql","ssh-tunnel"],"author":{"url":"https://github.com/abelmferreira","name":"Abel Ferreira"},"license":"MIT","_id":"@abelmferreira/mcp-mysql@1.0.0","maintainers":[{"name":"abelmferreira","email":"abelmferreira@gmail.com"}],"contributors":[{"url":"author of the original @fabriciofs/mcp-postgres, https://github.com/fabriciofs/mcp-postgres","name":"fabriciofs"}],"homepage":"https://github.com/abelmferreira/mcp-mysql#readme","bugs":{"url":"https://github.com/abelmferreira/mcp-mysql/issues"},"bin":{"mcp-mysql":"build/index.js"},"dist":{"shasum":"a5b243fa3b0a6709036358c45f9598ef1471ce53","tarball":"https://registry.npmjs.org/@abelmferreira/mcp-mysql/-/mcp-mysql-1.0.0.tgz","fileCount":175,"integrity":"sha512-kKq7rvGT0uiwksH7EVw7ZIJPuUHQATV8Ra49sYfdHKcVVc9Y93+dzJrDu3YhaLhWmXfg2hlFrCnHHQHDcLHsSA==","signatures":[{"sig":"MEYCIQCF1PjOfDdb8yWnidJ2RbfTMtyxPS8JwEqktV0VAJe0OAIhAKkK2ZChTZhBdb83A+GTbibN9QfPzH/MFQFLJM89yTPc","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIA2D6EJ+8WHyj0AgHlOHzEhCRvtaCyHQXeEUsBYFh3pjAiBr/RlTtRx2rIG02ffwnPRATPCktnkaoM/0YXEBsOqM/w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":434975},"main":"build/index.js","type":"module","types":"./build/index.d.ts","engines":{"node":">=20.12.0"},"gitHead":"415f989c71e90241731490861d5056089371b0b2","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","clean":"rm -rf build","start":"node --env-file=.env build/index.js","prepare":"npm run build","rebuild":"npm run clean && npm run build","inspector":"npx @modelcontextprotocol/inspector","typecheck":"tsc --noEmit","start:prod":"node build/index.js","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run typecheck && npm test && npm run build"},"_npmUser":{"name":"abelmferreira","email":"abelmferreira@gmail.com"},"repository":{"url":"git+https://github.com/abelmferreira/mcp-mysql.git","type":"git"},"_npmVersion":"10.9.8","description":"MCP server for MySQL/MariaDB: query, monitor and analyze with read-only mode and SSH tunnel","directories":{},"_nodeVersion":"22.23.2","dependencies":{"zod":"^4.2.1","ssh2":"^1.17.0","mysql2":"^3.11.0","@modelcontextprotocol/sdk":"^1.25.1"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.8","typescript":"^5.9.3","@types/node":"^25.0.2","@types/ssh2":"^1.15.5","@vitest/coverage-v8":"^2.1.8"},"_npmOperationalInternal":{"tmp":"tmp/mcp-mysql_1.0.0_1793656869661_0.5088853589910916","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@abelmferreira/mcp-mysql","version":"1.0.1","keywords":["anthropic","claude","claude-code","database","mariadb","mcp","mcp-server","model-context-protocol","mysql","read-only","sql","ssh-tunnel"],"author":{"url":"https://github.com/abelmferreira","name":"Abel Ferreira"},"license":"MIT","_id":"@abelmferreira/mcp-mysql@1.0.1","maintainers":[{"name":"abelmferreira","email":"abelmferreira@gmail.com"}],"contributors":[{"url":"author of the original @fabriciofs/mcp-postgres, https://github.com/fabriciofs/mcp-postgres","name":"fabriciofs"}],"homepage":"https://github.com/abelmferreira/mcp-mysql#readme","bugs":{"url":"https://github.com/abelmferreira/mcp-mysql/issues"},"bin":{"mcp-mysql":"build/index.js"},"dist":{"shasum":"bb475d86d0b0cb744c65a869fc9c11dbbbbe476a","tarball":"https://registry.npmjs.org/@abelmferreira/mcp-mysql/-/mcp-mysql-1.0.1.tgz","fileCount":175,"integrity":"sha512-YXfv0UHN8vIy2GaBaE2zjuci2HA7ELk3el7AOXCYYjtc/SPgjq+CqWOvEsTaKrXa4aJMiGNie1UCya6KunTSWQ==","signatures":[{"sig":"MEUCIEV5MnnyFuZAwhqkXGE+r4lkM/gqfDjXMzkvfkOMhv1kAiEA/BVZK/R1ttIEUxw6UdX566ytbu9ITKum8TNpgxhLrTA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIG19aPjFzIgwVV1iz5GLANKTqrFL2ul36EnI86XLkIxiAiEA/p+5Pf+QQ9DhQSKUoAs098Fk24l0YISW2+V1s2cfJWg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@abelmferreira%2fmcp-mysql@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":434975},"main":"build/index.js","type":"module","types":"./build/index.d.ts","engines":{"node":">=20.12.0"},"gitHead":"18083ec789a315deb149dac3bddcd3272b4b19ce","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","clean":"rm -rf build","start":"node --env-file=.env build/index.js","prepare":"npm run build","rebuild":"npm run clean && npm run build","inspector":"npx @modelcontextprotocol/inspector","typecheck":"tsc --noEmit","start:prod":"node build/index.js","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run typecheck && npm test && npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"a85ccdea-e328-4231-8127-243632411326"}},"repository":{"url":"git+https://github.com/abelmferreira/mcp-mysql.git","type":"git"},"_npmVersion":"11.21.1","description":"MCP server for MySQL/MariaDB: query, monitor and analyze with read-only mode and SSH tunnel","directories":{},"_nodeVersion":"22.23.4","dependencies":{"zod":"^4.2.1","ssh2":"^1.17.0","mysql2":"^3.11.0","@modelcontextprotocol/sdk":"^1.25.1"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.8","typescript":"^5.9.3","@types/node":"^25.0.2","@types/ssh2":"^1.15.5","@vitest/coverage-v8":"^2.1.8"},"_npmOperationalInternal":{"tmp":"tmp/mcp-mysql_1.0.1_1793658091776_0.30392750751056963","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"_id":"@abelmferreira/mcp-mysql@1.0.2","bin":{"mcp-mysql":"build/index.js"},"bugs":{"url":"https://github.com/abelmferreira/mcp-mysql/issues"},"dist":{"shasum":"e649dc64369514ca2d3612fb976dbf0c7fa09f8b","tarball":"https://registry.npmjs.org/@abelmferreira/mcp-mysql/-/mcp-mysql-1.0.2.tgz","fileCount":179,"integrity":"sha512-3odGxkBKIE3xf81oBd1ZLWSYgsV5xOosi1NWQxQKcl6jHMVPLqkNPuN5y/aA12FQeUGUgTNDMkWe+Ahl7UuiYg==","signatures":[{"sig":"MEQCIDvX9WA3VKFN4kwFB5mpjcvKOY7vlK7f61xH14ughQsPAiAC/RhAe4urocrfVB5yr5oeoKEyEVtepfxcdiML0VooQA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDKnmwif5lmfghu7M/6FbOXlfHlhf2/ZUYxHt6Jq/3hHgIhAPtOeisY8iT/6WHLiBj57gCmRmN6wTXg5fE+lJeqwu43"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@abelmferreira%2fmcp-mysql@1.0.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":468071},"main":"build/index.js","name":"@abelmferreira/mcp-mysql","type":"module","types":"./build/index.d.ts","author":{"url":"https://github.com/abelmferreira","name":"Abel Ferreira"},"engines":{"node":">=20.12.0"},"gitHead":"578d8f438324ae9484e34dd33dfc976f402045c4","license":"MIT","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","clean":"rm -rf build","start":"node --env-file=.env build/index.js","prepare":"npm run build","rebuild":"npm run clean && npm run build","inspector":"npx @modelcontextprotocol/inspector","typecheck":"tsc --noEmit","start:prod":"node build/index.js","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run typecheck && npm test && npm run build"},"version":"1.0.2","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"a85ccdea-e328-4231-8127-243632411326"}},"homepage":"https://github.com/abelmferreira/mcp-mysql#readme","keywords":["anthropic","claude","claude-code","database","mariadb","mcp","mcp-server","model-context-protocol","mysql","read-only","sql","ssh-tunnel"],"repository":{"url":"git+https://github.com/abelmferreira/mcp-mysql.git","type":"git"},"_npmVersion":"11.21.1","description":"MCP server for MySQL/MariaDB: query, monitor and analyze with read-only mode and SSH tunnel","directories":{},"maintainers":[{"name":"abelmferreira","email":"abelmferreira@gmail.com"}],"_nodeVersion":"22.23.4","contributors":[{"url":"author of the original @fabriciofs/mcp-postgres, https://github.com/fabriciofs/mcp-postgres","name":"fabriciofs"}],"dependencies":{"zod":"^4.2.1","ssh2":"^1.17.0","mysql2":"^3.11.0","@modelcontextprotocol/sdk":"^1.25.1"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.8","typescript":"^5.9.3","@types/node":"^25.0.2","@types/ssh2":"^1.15.5","@vitest/coverage-v8":"^2.1.8"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-mysql_1.0.2_1793668220421_0.19972397276016063"}}},"time":{"created":"2026-11-02T22:00:13.876Z","modified":"2026-11-03T01:10:20.874Z","0.0.0-stage":"2026-11-02T22:00:13.876Z","1.0.0":"2026-11-02T22:01:09.791Z","1.0.1":"2026-11-02T22:21:31.877Z","1.0.2":"2026-11-03T01:10:20.518Z"},"bugs":{"url":"https://github.com/abelmferreira/mcp-mysql/issues"},"author":{"url":"https://github.com/abelmferreira","name":"Abel Ferreira"},"license":"MIT","homepage":"https://github.com/abelmferreira/mcp-mysql#readme","keywords":["anthropic","claude","claude-code","database","mariadb","mcp","mcp-server","model-context-protocol","mysql","read-only","sql","ssh-tunnel"],"repository":{"url":"git+https://github.com/abelmferreira/mcp-mysql.git","type":"git"},"description":"MCP server for MySQL/MariaDB: query, monitor and analyze with read-only mode and SSH tunnel","contributors":[{"url":"author of the original @fabriciofs/mcp-postgres, https://github.com/fabriciofs/mcp-postgres","name":"fabriciofs"}],"maintainers":[{"name":"abelmferreira","email":"abelmferreira@gmail.com"}],"readme":"# MCP MySQL\n\n[![npm version](https://img.shields.io/npm/v/%40abelmferreira%2Fmcp-mysql)](https://www.npmjs.com/package/@abelmferreira/mcp-mysql)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20.12-green.svg)](https://nodejs.org/)\n\nA Model Context Protocol (MCP) server for **MySQL and MariaDB**. Query, monitor and analyze your databases directly from Claude Code (or any MCP client), read-only by default, with an optional built-in SSH tunnel.\n\nIt is a MySQL/MariaDB port of [`@fabriciofs/mcp-postgres`](https://github.com/fabriciofs/mcp-postgres): same tool surface and `READONLY` safety model, with all SQL rewritten for MySQL (`information_schema`, `performance_schema` and the `sys` schema).\n\n## Features\n\n- **Query execution** - `SELECT` / `WITH` / `EXPLAIN` / `DESCRIBE` / read-only `SHOW` with named `@param` placeholders (rendered as escaped literals by the server itself, then validated as a whole).\n- **Schema exploration** - tables, views, columns, indexes, stored procedures, full table description.\n- **Monitoring** - active queries, connections, InnoDB lock waits, wait stats, database size, performance counters.\n- **Performance analysis** - index suggestions, unused/redundant indexes, fragmentation, statistics freshness, `EXPLAIN` plans.\n- **Read-only by design** - several independent layers of protection (see [Security](#security)).\n- **Built-in SSH tunnel** - reach a database behind a bastion host with nothing but environment variables; the host key is always pinned.\n- **Write operations** (`INSERT` / `UPDATE` / `DELETE`) only when explicitly enabled with `READONLY=false`.\n\n## Requirements\n\n- Node.js **>= 20.12** (only for the `npx` usage), or Docker.\n- MySQL 8.0+ or MariaDB 10.5+ recommended. Some monitoring/analysis tools rely on `performance_schema` and the `sys` schema.\n\n## Quick start\n\nThe recommended way is `npx`, configured in your MCP client. For Claude Code, add it to `.mcp.json` in your project (or use `claude mcp add`). Every setting is an environment variable, passed in the `env` block.\n\n### 1. Direct connection\n\n```json\n{\n  \"mcpServers\": {\n    \"mydb\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@abelmferreira/mcp-mysql\"],\n      \"env\": {\n        \"SQL_CONNECTION_URL\": \"mysql://readonly_user:password@db.example.com:3306/mydb\",\n        \"READONLY\": \"true\"\n      }\n    }\n  }\n}\n```\n\nOr with individual parameters instead of the URL:\n\n```json\n\"env\": {\n  \"SQL_SERVER\": \"db.example.com\",\n  \"SQL_PORT\": \"3306\",\n  \"SQL_DATABASE\": \"mydb\",\n  \"SQL_USER\": \"readonly_user\",\n  \"SQL_PASSWORD\": \"password\",\n  \"READONLY\": \"true\"\n}\n```\n\n### 2. Through an SSH tunnel (environment variables only)\n\nWhen `SSH_HOST` is set the server opens the tunnel itself (an in-process `ssh -L` on a random `127.0.0.1` port). No `ssh` binary, helper script or Docker is needed. `SQL_SERVER:SQL_PORT` is the database address **as seen from the SSH host**.\n\n```json\n{\n  \"mcpServers\": {\n    \"mydb\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@abelmferreira/mcp-mysql\"],\n      \"env\": {\n        \"SQL_SERVER\": \"192.0.2.10\",\n        \"SQL_PORT\": \"3306\",\n        \"SQL_DATABASE\": \"mydb\",\n        \"SQL_USER\": \"readonly_user\",\n        \"SQL_PASSWORD\": \"password\",\n        \"READONLY\": \"true\",\n        \"SSH_HOST\": \"bastion.example.com\",\n        \"SSH_USER\": \"tunnel\",\n        \"SSH_KEY_PATH\": \"~/.ssh/mcp_tunnel_key\",\n        \"SSH_HOST_FINGERPRINT\": \"SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\n- `SSH_KEY_PATH` is a path on the machine running the MCP server. `~` is expanded; relative paths are resolved against the working directory chosen by the MCP client, so prefer absolute or `~/` paths.\n- Encrypted keys need `SSH_KEY_PASSPHRASE`. A dedicated key without passphrase, restricted on the server (see below), is usually simpler.\n- `SSH_HOST_FINGERPRINT` is mandatory: the host key is always verified and there is no \"trust on first use\". Get it with `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub` on the server, or `ssh-keyscan bastion.example.com | ssh-keygen -lf -` (and confirm it through another channel). A comma separated list is accepted (one per host key algorithm).\n- The SSH session is opened at startup, so a bad key, host or fingerprint fails fast with a clear message on stderr. It is re-established automatically if it drops.\n\n**Restrict the tunnel key on the SSH server.** In `~/.ssh/authorized_keys` of the tunnel user:\n\n```\nrestrict,port-forwarding,permitopen=\"192.0.2.10:3306\",command=\"/usr/sbin/nologin\" ssh-ed25519 AAAA... mcp-tunnel\n```\n\n`restrict` disables everything (PTY, agent/X11 forwarding, user rc), `port-forwarding` re-enables only local forwarding, and `permitopen` limits it to the database address. `restrict` alone does **not** stop the key from running commands or opening a shell, so `command=\"/usr/sbin/nologin\"` is needed to make it useless for anything but the tunnel.\n\n### 3. Pointing to a project `.env` file (`ENV_FILE`)\n\nKeep the configuration in a `.env` file of your project (git-ignored) and point the server at it:\n\n```json\n{\n  \"mcpServers\": {\n    \"mydb\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@abelmferreira/mcp-mysql\"],\n      \"env\": {\n        \"ENV_FILE\": \"/path/to/project/.env\"\n      }\n    }\n  }\n}\n```\n\n- The file uses the usual dotenv syntax (`KEY=value`, `# comments`, quotes) and may contain any variable from the [table below](#environment-variables), including `SSH_*`.\n- Variables set in the `env` block **win** over the file (same precedence as `node --env-file`), so you can share one file and override, for example, `READONLY` per client.\n- `~` is expanded; relative paths are resolved against the working directory of the server process.\n- A missing or unreadable file stops the server with an error on stderr (exit code 1). Values are never logged.\n\n### 4. Docker\n\nA public image is available on Docker Hub as `abelmferreira/mcp-mysql`. The server speaks MCP over stdio, so run it with `-i` and without `-t`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mydb\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\",\n        \"--env-file\", \"/path/to/project/.env\",\n        \"abelmferreira/mcp-mysql\"\n      ]\n    }\n  }\n}\n```\n\nWith the SSH tunnel, mount the key read-only and point `SSH_KEY_PATH` at the path **inside** the container:\n\n```json\n\"args\": [\n  \"run\", \"-i\", \"--rm\",\n  \"--env-file\", \"/path/to/project/.env\",\n  \"-e\", \"SSH_KEY_PATH=/run/secrets/ssh_key\",\n  \"-v\", \"/home/me/.ssh/mcp_tunnel_key:/run/secrets/ssh_key:ro\",\n  \"abelmferreira/mcp-mysql\"\n]\n```\n\nNotes for Docker:\n\n- `--env-file` is read by Docker itself, so use it instead of `ENV_FILE` (the container cannot see host paths unless you mount them). Docker's `--env-file` does not strip quotes: write `KEY=value`, not `KEY=\"value\"`.\n- If the database runs on the Docker host, use `host.docker.internal` (add `--add-host=host.docker.internal:host-gateway` on Linux) instead of `localhost`.\n- The SSH tunnel listens on `127.0.0.1` inside the container only.\n\n## Environment variables\n\n| Variable | Required | Default | Description |\n| -------- | -------- | ------- | ----------- |\n| `ENV_FILE` | no | - | Path of a dotenv file to load first. Variables already in the environment win. `~` and relative paths are supported |\n| `SQL_CONNECTION_URL` | no\\* | - | `mysql://user:pass@host:port/database?ssl=true` (`mariadb://` also accepted; URL-encode special characters in the password) |\n| `SQL_SERVER` | no\\* | - | Database host (as seen from the SSH host when the tunnel is enabled) |\n| `SQL_DATABASE` | no\\* | - | Database name |\n| `SQL_USER` | no\\* | - | Username |\n| `SQL_PASSWORD` | no\\* | - | Password |\n| `SQL_PORT` | no | `3306` | Port |\n| `SQL_SSL` | no | `false` | Enable TLS to the database. The server certificate **is verified** (see [TLS](#tls)) |\n| `SQL_SSL_CA` | no | - | PEM file of the CA that signed the database certificate (`~` supported). Without it the system CA store is used |\n| `SQL_SSL_REJECT_UNAUTHORIZED` | no | `true` | `false` disables certificate verification (not recommended; a warning is logged) |\n| `READONLY` | **yes** | - | `true` (read-only, recommended) or `false` (enables write tools) |\n| `QUERY_TIMEOUT` | no | `30000` | Statement timeout in ms (max `120000`), enforced by the server and by the client |\n| `MAX_ROWS` | no | `1000` | Max rows returned per query (max `5000`); caps the `maxRows` argument of the tools |\n| `MAX_RESULT_BYTES` | no | `1048576` (1 MiB) | Max size of one query result (approximate, in bytes; `1024`..`104857600`). Larger results are cut and flagged `truncated` |\n| `POOL_MAX` | no | `3` | Maximum connections open on the database at the same time (`1`..`50`); further queries wait in a FIFO queue. Keep it below the account's `max_user_connections` (leave room for its other clients); raise it if the account allows more. `POOL_MIN` is no longer used and is ignored |\n| `LOG_LEVEL` | no | `info` | `debug`, `info`, `warn`, `error` (logs go to stderr) |\n| `SSH_HOST` | no | - | Enables the built-in SSH tunnel |\n| `SSH_PORT` | no | `22` | SSH port |\n| `SSH_USER` | with `SSH_HOST` | - | SSH user |\n| `SSH_KEY_PATH` | with `SSH_HOST` | - | Private key path (`~` supported; inside the container when using Docker) |\n| `SSH_KEY_PASSPHRASE` | no | - | Passphrase of an encrypted key |\n| `SSH_HOST_FINGERPRINT` | with `SSH_HOST` | - | Pinned host key fingerprint(s), `SHA256:...`, comma separated |\n\n\\* Provide either `SQL_CONNECTION_URL` **or** `SQL_SERVER`, `SQL_DATABASE`, `SQL_USER` and `SQL_PASSWORD`. When the URL is set it takes precedence. See [`.env.example`](.env.example) for a commented template.\n\n## Security\n\nThe server is meant to be driven by an AI assistant, which can be manipulated by the content it reads (prompt injection). Read-only access is therefore enforced by several independent layers. **The first one is the real boundary**; the others are defence in depth and must not be relied upon alone.\n\n### 1. A database account that can only read (the real boundary)\n\nCreate a dedicated user with `SELECT` only, on the databases it needs:\n\n```sql\nCREATE USER 'mcp_readonly'@'%' IDENTIFIED BY 'a-strong-password';\nGRANT SELECT ON mydb.* TO 'mcp_readonly'@'%';\n-- optional, for the monitor/analyze tools:\nGRANT SELECT ON performance_schema.* TO 'mcp_readonly'@'%';\nGRANT SELECT ON sys.* TO 'mcp_readonly'@'%';\n```\n\n- Restrict the host part (`'%'`) to where the server connects from (for example the SSH host).\n- **Do not grant `FILE`** (`LOAD_FILE()`, `INTO OUTFILE`), `PROCESS` (it shows the text of every running query, including other users' literals), `SUPER` or any admin privilege, and no `EXECUTE` on routines that write. Do not grant `SELECT` on the `mysql` schema (credential hashes) nor on tables holding secrets you do not want an AI assistant to read.\n- Without `PROCESS`/`performance_schema` privileges the monitor and analyze tools still work, with less information and an explicit `warnings` entry.\n- User-defined functions (UDFs, e.g. `sys_exec` from lib_mysqludf_sys) and stored functions can do anything; a keyword list cannot know them. Only the GRANT can stop them.\n\n### 2. Query validator (`READONLY=true`)\n\nA lexer that mirrors the MySQL/MariaDB one splits the query into tokens (string literals, `` `quoted identifiers` ``, comments, variables, words). The same lexer is used to bind `@param` placeholders, so the validator checks **the exact text sent to the server**. It accepts exactly one statement starting with `SELECT`, `WITH`, `EXPLAIN`/`DESCRIBE`/`DESC`, `TABLE`, `VALUES`, `(SELECT ...)`, or one of these `SHOW` forms: `SHOW [FULL] TABLES`, `SHOW [FULL] COLUMNS`, `SHOW INDEX`, `SHOW TABLE STATUS`, `SHOW CREATE TABLE`/`VIEW`, `SHOW [GLOBAL|SESSION] STATUS`/`VARIABLES`, `SHOW DATABASES`. It rejects:\n\n- multiple statements, executable comments (`/*! ... */`, `/*M! ... */`) and optimizer hints (`/*+ ... */`, which could override the statement timeout or the sql_mode);\n- non-ASCII or control characters outside string literals, quoted identifiers and comments (use backticks for non-ASCII identifiers), and NUL characters anywhere;\n- reserved write/DDL keywords anywhere (`INSERT`, `UPDATE`, `DELETE`, `CREATE`, `DROP`, `ALTER`, `RENAME`, `GRANT`, `REVOKE`, `CALL`, `LOAD`, `LOCK`, `UNLOCK`), `INTO` (`OUTFILE`, `DUMPFILE`, `@var`), locking clauses (`FOR UPDATE`, `FOR SHARE`, `LOCK IN SHARE MODE`) and `EXPLAIN ... FOR CONNECTION`;\n- side-effect, blocking or state-changing functions: `SLEEP`, `BENCHMARK`, `LOAD_FILE`, `GET_LOCK`, `RELEASE_LOCK`, `RELEASE_ALL_LOCKS`, the locking service functions, replication waits (`MASTER_POS_WAIT`, `SOURCE_POS_WAIT`, `MASTER_GTID_WAIT`, `WAIT_FOR_EXECUTED_GTID_SET`, ...), MariaDB sequences (`NEXTVAL`, `SETVAL`, `NEXT VALUE FOR`), `GROUP_REPLICATION_*`, `ASYNCHRONOUS_CONNECTION_FAILOVER_*` and the well-known `sys_exec`/`sys_eval` UDFs;\n- user variables (`@x`, `` @`x` ``, `@x := ...`): only `@name` placeholders that have a value in `params` are accepted, `@@system_variables` can be read. Positional `?` placeholders are not supported;\n- credential objects, best effort: `mysql.user`, `mysql.global_priv`, `authentication_string`, `slave_master_info`.\n\nStatement-only keywords that are not reserved (`HANDLER`, `RESET`, `FLUSH`, `KILL`, `EXECUTE`, `PREPARE`, `SHUTDOWN`, `TRUNCATE`, ...) can be used as column names, and a reserved word right after a dot (`t.delete`) is an identifier, as it is for the server.\n\n### 3. Read-only, short-lived sessions\n\nWith `READONLY=true` each query runs on its own connection:\n\n- the session `sql_mode` is checked first. `NO_BACKSLASH_ESCAPES` and `ANSI_QUOTES` (and the combination modes that imply it: `ANSI`, `ORACLE`, `DB2`, `MSSQL`, `POSTGRESQL`, `MAXDB`) change how string literals are read, which the validator and the parameter escaping rely on: they are removed from the session `sql_mode` (no privilege needed); if that does not stick, the query is refused;\n- a server-side statement timeout is set (`max_statement_time` on MariaDB, `max_execution_time` on MySQL). If neither can be set, the query is refused. A client-side timer (`QUERY_TIMEOUT` + 1 s) also aborts the query, with a `KILL QUERY` on another connection (an account can always kill its own threads; skipped with `POOL_MAX=1`, where the server-side timeout ends the statement);\n- the statement runs inside `START TRANSACTION READ ONLY`, so even a `SELECT f()` where `f` writes is refused by the database;\n- rows are streamed and reading stops at `maxRows` (capped by `MAX_ROWS`) or `MAX_RESULT_BYTES`; the connection is then dropped, so a huge result never fills the memory of the process;\n- the connection is closed afterwards and never reused, so no session state survives a query (user-level locks, user variables, `LAST_INSERT_ID(x)`, temporary tables). This costs one new connection per query (through the SSH tunnel: a new forwarded channel on the same SSH session).\n\n### Connection limits\n\nThe server never has more than `POOL_MAX` connections open from this process, in both modes: further queries wait in a FIFO queue. A slot is freed only when the server has really dropped the connection (the socket closed after `COM_QUIT`; after an aborted result or a timeout, 500 ms later, since the client cannot observe it), so a closing connection and its replacement are never counted together against `max_user_connections`. With `POOL_MAX=1` every tool still works (the tools run their queries one after the other).\n\nWhen the server still refuses a connection because a limit is reached by other clients (`1226 ER_USER_LIMIT_REACHED` for the account's `max_user_connections`, `1040 ER_CON_COUNT_ERROR` for the server's `max_connections`), the connection is retried 3 times (200/400/800 ms plus jitter, within `QUERY_TIMEOUT`); then the tool fails with a message that explains the limit and suggests lowering `POOL_MAX`.\n\n### TLS\n\nWith `SQL_SSL=true` the database certificate is verified against the system CA store or `SQL_SSL_CA`. On direct connections the host name is verified too; through the SSH tunnel the driver connects to `127.0.0.1`, so only the certificate chain is verified (the tunnel itself is authenticated by the pinned host key). `SQL_SSL_REJECT_UNAUTHORIZED=false` disables verification (a warning is logged). The URL form accepts `?ssl=true`.\n\n### Other measures\n\nThe SSH host key is always verified against `SSH_HOST_FINGERPRINT` (format checked at startup; on mismatch the received fingerprint is logged to stderr so it can be compared), the tunnel listens on `127.0.0.1` only, passwords are redacted from logs, logs carry a short hash of the query instead of its text, errors returned to the client do not contain account names or IP addresses, and nothing but MCP protocol messages is written to stdout.\n\n### Known limitations\n\n- The validator is a blocklist on top of an allowlist of statement types: it cannot know UDFs or stored functions, and it is not a substitute for the GRANT.\n- MySQL's `max_execution_time` only applies to `SELECT`; `SHOW`/`EXPLAIN` are bounded by the client-side timer.\n- `MAX_RESULT_BYTES` (1 MiB by default) is approximate, and a single row can still be as large as the server's `max_allowed_packet`.\n- Keep `READONLY=true` unless you really need the write tools: with `READONLY=false` none of the checks above applies to `sql_execute` (only the `sql_mode` check, which keeps parameter escaping correct).\n\n## Available tools\n\n| Category | Tools |\n| -------- | ----- |\n| Query | `sql_execute` |\n| Schema | `schema_list_tables`, `schema_list_columns`, `schema_describe_table`, `schema_list_indexes`, `schema_list_procedures` |\n| Monitor | `monitor_active_queries`, `monitor_connections`, `monitor_blocking`, `monitor_wait_stats`, `monitor_database_size`, `monitor_performance_counters` |\n| Analyze | `analyze_query`, `analyze_suggest_indexes`, `analyze_unused_indexes`, `analyze_duplicate_indexes`, `analyze_fragmentation`, `analyze_statistics` |\n| Write\\* | `sql_insert`, `sql_update`, `sql_delete` |\n\n\\* Only registered when `READONLY=false`.\n\nIn MySQL \"schema\" and \"database\" are synonyms: the `schema` argument of the tools is a database name and defaults to the connected database.\n\nNotes on the tools:\n\n- `sql_execute` returns `rows`, `rowCount` (rows returned), `fields`, `duration` and `truncated`; when `truncated` is `true` there were more rows (or more data) than returned.\n- `analyze_query` only accepts `SELECT`/`WITH` queries. Digest statistics need MySQL 8 with `performance_schema` (`STATEMENT_DIGEST()`); on MariaDB only the plan is returned.\n- Tools based on `performance_schema` or the `sys` schema (`monitor_wait_stats`, `analyze_suggest_indexes`, `analyze_unused_indexes`, the usage counters of `schema_list_indexes`, digest statistics) return an explicit warning when `performance_schema` is disabled (the MariaDB default) or not readable, instead of an empty result. `monitor_performance_counters` uses `SHOW GLOBAL STATUS` and works everywhere.\n- Arguments removed because MySQL has no data for them: `minImpact` (`analyze_suggest_indexes`), `minSizeMB`/`minAgeDays` (`analyze_unused_indexes`), `minRowsChanged` (`analyze_statistics`). `analyze_fragmentation` `minPageCount` now filters by table size in InnoDB pages (default `0`).\n\n## Development\n\nClone the repository, then use Docker so nothing has to be installed on the host:\n\n```bash\ngit clone https://github.com/abelmferreira/mcp-mysql.git\ncd mcp-mysql\n\n# Typecheck + unit tests (no database needed)\ndocker build --target test .\n\n# Or interactively\ndocker run --rm -v \"$PWD\":/app -w /app node:22-alpine \\\n  sh -c 'npm ci && npm run typecheck && npm test && npm run build'\n\n# Local image\ndocker build -t mcp-mysql:local .\n```\n\nA throwaway MySQL for manual testing is available in `docker-compose.yml`:\n\n```bash\ncp .env.example .env      # adjust; SQL_SERVER is overridden to the compose service\ndocker compose up -d mysql\ndocker compose run --rm mcp-mysql\n```\n\nWith Node.js >= 20.12 on the host the usual scripts work too: `npm ci`, `npm run build`, `npm test`, `npm start` (reads `./.env`), `npm run inspector` (MCP Inspector).\n\n## Acknowledgements\n\nThis project is a port to MySQL/MariaDB of [**mcp-postgres**](https://github.com/fabriciofs/mcp-postgres) ([`@fabriciofs/mcp-postgres`](https://www.npmjs.com/package/@fabriciofs/mcp-postgres)) by **fabriciofs**, released under the MIT License. The tool set, the `READONLY` model and the overall structure come from it; the SQL, the validator, the read-only transaction and the SSH tunnel were rewritten or added for MySQL/MariaDB.\n\n## License\n\n[MIT](LICENSE). Copyright (c) 2024 fabriciofs (original work) and (c) 2026 Abel Ferreira (MySQL/MariaDB port).\n","readmeFilename":"README.md"}