{"_id":"mysql2-mcp-server","_rev":"4-64365950eebbea53e6fede6f00d110ac","name":"mysql2-mcp-server","dist-tags":{"latest":"2.1.0"},"versions":{"1.3.0":{"name":"mysql2-mcp-server","version":"1.3.0","keywords":["mcp","mysql","mysql2","model-context-protocol","ssh-tunnel","database","ai-tools"],"author":{"name":"jcxy"},"license":"MIT","_id":"mysql2-mcp-server@1.3.0","maintainers":[{"name":"cvtoolman","email":"1292307821@qq.com"}],"homepage":"https://github.com/jcxy/mysql-mcp-server#readme","bugs":{"url":"https://github.com/jcxy/mysql-mcp-server/issues"},"bin":{"mysql2-mcp-server":"index.js"},"dist":{"shasum":"a451e9cc418d4686449b5a40606e26bf85265818","tarball":"https://registry.npmjs.org/mysql2-mcp-server/-/mysql2-mcp-server-1.3.0.tgz","fileCount":10,"integrity":"sha512-jMi9XjmYJP9aSeNgSmEEEmtuoIX7OP95ZFjwk0ouwrGtd0Vf53M5f/420aK40s2CZhqlhDrbkao2K7tphxA9OQ==","signatures":[{"sig":"MEUCIQC5oWEOb99bJZGIZ6bMyPUW7a5rqwwcRBKLFo2SAmufpgIgTqmT/Ud1DxSY1SnWQ+sN5FTLuDPtawByfc4RVSYjqGE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":35106},"main":"index.js","type":"module","engines":{"node":">=18.14.1"},"gitHead":"12d457ef5928f93bf62c9a9851b3c7fb48561ef0","scripts":{"test":"node smoke-test.js","start":"node index.js","prepublishOnly":"node smoke-test.js"},"_npmUser":{"name":"cvtoolman","email":"1292307821@qq.com"},"repository":{"url":"git+https://github.com/jcxy/mysql-mcp-server.git","type":"git"},"_npmVersion":"11.11.0","description":"MySQL MCP server that enables AI assistants to interact with MySQL databases. Supports direct connection, SSH tunnel, connection pool, transactions, and security enforcement.","directories":{},"_nodeVersion":"24.14.1","dependencies":{"ssh2":"^1.17.0","mysql2":"^3.18.0","@modelcontextprotocol/sdk":"^1.27.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mysql2-mcp-server_1.3.0_1790260208163_0.5352740613211646","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"mysql2-mcp-server","version":"2.0.0","keywords":["mcp","mysql","mysql2","model-context-protocol","ssh-tunnel","database","ai-tools"],"author":{"name":"jcxy"},"license":"MIT","_id":"mysql2-mcp-server@2.0.0","maintainers":[{"name":"cvtoolman","email":"1292307821@qq.com"}],"homepage":"https://github.com/jcxy/mysql-mcp-server#readme","bugs":{"url":"https://github.com/jcxy/mysql-mcp-server/issues"},"bin":{"mysql2-mcp-server":"index.js"},"dist":{"shasum":"0da46466df3d89684a1ed676dc7d35999e7c1ec2","tarball":"https://registry.npmjs.org/mysql2-mcp-server/-/mysql2-mcp-server-2.0.0.tgz","fileCount":12,"integrity":"sha512-blKWri65dRi+p/qA6sPtjzKDC0sgcb4AZddrH8VQe65MXYNvdmbIqibXhVSNJIgizqfyI089Ocice8R3xyfSqQ==","signatures":[{"sig":"MEQCIGBpgF1l6a+Z6ZoMf3otonMuBtrHOvqP8K6EVJvqsA+fAiAV44wqxvHjmW9D5iseY6uv8vGQZtkU2y5jQU+F5w0bww==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQCpT3UisobPGWWzweYEkMHnpuuti/w/LdhHnnvi3off9AIgXPfSmJuLhgM/ZPnm+CxZioINUXlm1MV1cjl5z/qJeeY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/mysql2-mcp-server@2.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":66279},"main":"index.js","type":"module","engines":{"node":">=18.14.1"},"gitHead":"b48a15210e2e6cf6405c84997e04012e756072ce","scripts":{"test":"node smoke-test.js","start":"node index.js","prepublishOnly":"node smoke-test.js"},"_npmUser":{"name":"cvtoolman","email":"1292307821@qq.com"},"repository":{"url":"git+https://github.com/jcxy/mysql-mcp-server.git","type":"git"},"_npmVersion":"10.8.2","description":"MySQL MCP server that enables AI assistants to interact with MySQL databases. Supports direct connection, SSH tunnel, connection pool, transactions, and security enforcement.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"ssh2":"^1.17.0","mysql2":"^3.18.0","@modelcontextprotocol/sdk":"^1.27.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mysql2-mcp-server_2.0.0_1791706323151_0.7020884928056239","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"name":"mysql2-mcp-server","version":"2.0.1","keywords":["mcp","mysql","mysql2","model-context-protocol","ssh-tunnel","database","ai-tools"],"author":{"name":"jcxy"},"license":"MIT","_id":"mysql2-mcp-server@2.0.1","maintainers":[{"name":"cvtoolman","email":"1292307821@qq.com"}],"homepage":"https://github.com/jcxy/mysql-mcp-server#readme","bugs":{"url":"https://github.com/jcxy/mysql-mcp-server/issues"},"bin":{"mysql2-mcp-server":"index.js"},"dist":{"shasum":"0ccd9ea5f78087b748456a8bb06a95a242425217","tarball":"https://registry.npmjs.org/mysql2-mcp-server/-/mysql2-mcp-server-2.0.1.tgz","fileCount":12,"integrity":"sha512-m6t0qdw7kf6udHxBcWBiS/LywMYGweW1gK151wj5kBoplFOIfNV7VQgU0uCgsuZu9dKkiRiGt6DO1yRn52hx3w==","signatures":[{"sig":"MEUCIGMfrn8HT8m1xwHRDG7D0ZckV8iimfa00J7ykaakorzxAiEAui09JzTmzz0LfXhG46JKI/DyxG9dmbtyRw/QSFmNsj0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIB57pH5nlhSFu9caqqbHZTW+mj1PRUXff7NQN/9z7MNJAiAm+cmujKBquQuyyljVuR34jEBxLTUa9S3T5tkj5+Q9dg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/mysql2-mcp-server@2.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":68638},"main":"index.js","type":"module","engines":{"node":">=18.14.1"},"gitHead":"17895bb227f6544a52aab0ba8e174f11fc8c8b12","scripts":{"test":"node smoke-test.js","start":"node index.js","prepublishOnly":"node smoke-test.js"},"_npmUser":{"name":"cvtoolman","email":"1292307821@qq.com"},"repository":{"url":"git+https://github.com/jcxy/mysql-mcp-server.git","type":"git"},"_npmVersion":"10.8.2","description":"MySQL MCP server that enables AI assistants to interact with MySQL databases. Supports direct connection, SSH tunnel, connection pool, transactions, and security enforcement.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"ssh2":"^1.17.0","mysql2":"^3.18.0","@modelcontextprotocol/sdk":"^1.27.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mysql2-mcp-server_2.0.1_1791707747605_0.0765713294275816","host":"s3://npm-registry-packages-npm-production"}},"2.1.0":{"_id":"mysql2-mcp-server@2.1.0","bin":{"mysql2-mcp-server":"index.js"},"bugs":{"url":"https://github.com/jcxy/mysql-mcp-server/issues"},"dist":{"shasum":"32c82f2bcaee670003e60bba1ba67fa56801726a","tarball":"https://registry.npmjs.org/mysql2-mcp-server/-/mysql2-mcp-server-2.1.0.tgz","fileCount":13,"integrity":"sha512-HiahJ4MC9uzDOhhcnjj4Rgzo3PEeJ7oH1H+K0zmvzO2EKrCSKC/UR7YTKv7DjYHO/NQN8MWlX01CVKPMJ7MwtQ==","signatures":[{"sig":"MEUCIBX36BdjyLQ/qljrfRRIIhrc+QhU4cl6i8SR+M2Xa2zqAiEAwY9ooYknfzIXB3U8cX7qLAvabOfbPrk/kZ9XU4psVJg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCRyKnVw0FaM6O+kEz0Y1WFCSoeohdpKQ5xhIhZ6FH/zgIhAOefgG5oUm768C1BiGD05LLIt27aXmF4V4rnb2VKR784"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/mysql2-mcp-server@2.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":82391},"main":"index.js","name":"mysql2-mcp-server","type":"module","author":{"name":"jcxy"},"engines":{"node":">=18.14.1"},"gitHead":"e517c833e6a2b8212281c0aa8bc2db8c657f26fd","license":"MIT","scripts":{"test":"node smoke-test.js","start":"node index.js","prepublishOnly":"node smoke-test.js"},"version":"2.1.0","_npmUser":{"name":"cvtoolman","email":"1292307821@qq.com"},"homepage":"https://github.com/jcxy/mysql-mcp-server#readme","keywords":["mcp","mcp-server","mysql","mysql2","mysql-mcp-server","model-context-protocol","ssh-tunnel","ssh","readonly","multi-environment","database","ai-tools","claude","claude-desktop","cursor"],"repository":{"url":"git+https://github.com/jcxy/mysql-mcp-server.git","type":"git"},"_npmVersion":"10.8.2","description":"MySQL MCP server that enables AI assistants to interact with MySQL databases. Supports direct connection, SSH tunnel, connection pool, transactions, and security enforcement.","directories":{},"maintainers":[{"name":"cvtoolman","email":"1292307821@qq.com"}],"_nodeVersion":"20.20.2","dependencies":{"ssh2":"^1.17.0","mysql2":"^3.18.0","@modelcontextprotocol/sdk":"^1.27.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mysql2-mcp-server_2.1.0_1793256891211_0.5331391255659386"}}},"time":{"created":"2026-09-24T14:30:08.115Z","modified":"2026-10-29T06:54:51.657Z","1.3.0":"2026-09-24T14:30:08.313Z","2.0.0":"2026-10-11T08:12:03.260Z","2.0.1":"2026-10-11T08:35:47.685Z","2.1.0":"2026-10-29T06:54:51.308Z"},"bugs":{"url":"https://github.com/jcxy/mysql-mcp-server/issues"},"author":{"name":"jcxy"},"license":"MIT","homepage":"https://github.com/jcxy/mysql-mcp-server#readme","keywords":["mcp","mcp-server","mysql","mysql2","mysql-mcp-server","model-context-protocol","ssh-tunnel","ssh","readonly","multi-environment","database","ai-tools","claude","claude-desktop","cursor"],"repository":{"url":"git+https://github.com/jcxy/mysql-mcp-server.git","type":"git"},"description":"MySQL MCP server that enables AI assistants to interact with MySQL databases. Supports direct connection, SSH tunnel, connection pool, transactions, and security enforcement.","maintainers":[{"name":"cvtoolman","email":"1292307821@qq.com"}],"readme":"# MySQL MCP Server\n\n[![npm version](https://img.shields.io/npm/v/mysql2-mcp-server)](https://www.npmjs.com/package/mysql2-mcp-server)\n[![npm downloads](https://img.shields.io/npm/dm/mysql2-mcp-server)](https://www.npmjs.com/package/mysql2-mcp-server)\n[![Node.js Version](https://img.shields.io/node/v/mysql2-mcp-server)](https://www.npmjs.com/package/mysql2-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![GitHub Issues](https://img.shields.io/github/issues/jcxy/mysql-mcp-server)](https://github.com/jcxy/mysql-mcp-server/issues)\n\n中文 | [English](./README.en.md)\n\n> 🌐 **English documentation**: see [README.en.md](./README.en.md)\n\n一个专注于 MySQL 的 MCP (Model Context Protocol) 服务器：**单实例管理任意多套环境（dev / uat / prod …，数量不限），prod 按环境只读硬拦截，内网库走 SSH 隧道（断线自动重连）**，让 AI 助手安全地与 MySQL 数据库交互。\n\n## 同类项目对比\n\n| 能力 | 本项目 | [designcomputer/mysql_mcp_server](https://github.com/designcomputer/mysql_mcp_server) | [bytebase/dbhub](https://github.com/bytebase/dbhub) |\n|---|---|---|---|\n| 单实例多环境（数量不限、任意命名、调用级路由 + 环境回显） | ✅ | ❌ | ⚠️ 多数据源（TOML，按 id 拆分工具） |\n| 按环境只读（`mysql_execute` / 事务整体禁用） | ✅ | ⚠️ 全局开关 | ✅ 按数据源/工具 |\n| SSH 隧道 | ✅ 断线自动重连（指数退避） | ❌ | ✅ |\n| 显式事务工具（`mysql_begin`/`mysql_commit`/`mysql_rollback`） | ✅ | ❌ | ⚠️ 多语句事务 |\n| 连接池 | ✅ | ❌ | 未标注 |\n| 数据库范围 | 仅 MySQL（专用、轻量） | 仅 MySQL | MySQL / PostgreSQL / SQLite 等 5 种 |\n| 安装 | npx / npm / Smithery | pip / uvx / Smithery | Docker / npx |\n\n> ⚠️ 表示部分支持或以不同形态提供；「未标注」指对方官方文档未明确说明。表中信息如有过时，欢迎提 PR 修正。\n\n## 演示：AI 试图删 prod 数据，被只读模式拦截\n\n```text\n你：帮我把 prod 库里 id=3 的订单删掉\n\nAI 调用 mysql_execute:\n  sql:         DELETE FROM orders WHERE id = 3\n  environment: prod\n\n返回:\n  当前环境 \"prod\" 为只读模式，变更语句已被禁用。如需执行变更，请切换到非只读环境或调整该环境的 readOnly 配置后重试。\n\nAI：prod 环境是只读的，我不能删除数据。需要我用 mysql_query 先帮你确认这条订单的状态吗？\n```\n\n每个工具的返回值都会回显实际作用的环境名，误路由在第一时间可见。MCP 侧只读是纵深防御的一层，硬保证请配合数据库侧最小权限账号（见[生产环境只读加固](#生产环境只读加固推荐)）。\n\n## 功能特性\n\n- 🔌 **双连接模式**: 支持直接连接和 SSH 隧道连接\n- 🔄 **SSH 自动重连**: SSH 隧道断线后自动重连（指数退避）\n- 🔗 **连接池**: 直连模式使用连接池，提升查询性能\n- 🔍 **查询执行**: 执行 SELECT 查询并返回结果\n- ✏️ **数据操作**: 执行 INSERT、UPDATE、DELETE 等语句\n- 📋 **Schema 探索**: 列出表、查看表结构，帮助 AI 快速了解数据库\n- 💼 **事务支持**: 支持 BEGIN/COMMIT/ROLLBACK（直连模式）\n- 🛡️ **安全机制**: 语句白名单、结果截断、按环境只读模式\n- 🌍 **多环境支持**: 单实例同时注册任意多套环境（dev/uat/prod…，数量不限、可任意命名），调用时显式 `environment` 参数路由\n- 🔐 **统一 JSON 配置**: 环境结构、权限与密码统一在一个 `~/.mysql-mcp/config.json`，MCP 配置零参数\n\n## 安装\n\n### 方式一：Smithery 一键安装（Claude Desktop）\n\n```bash\nnpx -y @smithery/cli install @jcxy/mysql2-mcp-server --client claude\n```\n\n### 方式二：npx 直接运行（推荐，无需克隆仓库）\n\n无需安装，MCP 客户端会通过 npx 自动下载并运行：\n\n```bash\nnpx -y mysql2-mcp-server\n```\n\n### 方式三：全局安装\n\n```bash\nnpm install -g mysql2-mcp-server\nmysql2-mcp-server\n```\n\n### 方式四：从源码运行\n\n```bash\ngit clone https://github.com/jcxy/mysql-mcp-server.git\ncd mysql-mcp-server\nnpm install\nnpm start\n```\n\n## 配置方式\n\n### 方式一：配置文件（推荐）\n\n在用户主目录创建 `~/.mysql-mcp/config.json`，服务器启动时自动加载（配置文件不存在时仅使用环境变量）：\n\n```bash\nmkdir -p ~/.mysql-mcp\ncp config.example.json ~/.mysql-mcp/config.json\n```\n\n单环境极简配置：\n\n```json\n{\n  \"host\": \"localhost\",\n  \"port\": 3306,\n  \"user\": \"root\",\n  \"password\": \"your_password\",\n  \"database\": \"your_database\"\n}\n```\n\n多环境配置见下方[多环境配置示例](#多环境配置示例)。路径可通过环境变量 `MYSQL_MCP_CONFIG_FILE` 覆盖（CI / 多套配置切换场景）。Linux/macOS 建议收紧权限：`chmod 600 ~/.mysql-mcp/config.json`（Windows 用户目录默认仅本人可读）。\n\n### 方式二：环境变量（单环境）\n\n在 MCP 客户端配置中通过环境变量传递数据库连接信息，无需任何文件。单环境优先级：环境变量 > `config.json` > 默认值。\n\n## 在 Claude Desktop 中使用\n\n### 配置文件位置\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n### MCP 客户端基础配置示例（npx 方式）\n\n数据库连接信息只存放在 `~/.mysql-mcp/config.json`（见上方「配置方式」），MCP 客户端配置中不出现任何账号密码：\n\n```json\n{\n  \"mcpServers\": {\n    \"mysql\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mysql2-mcp-server\"]\n    }\n  }\n}\n```\n\n环境变量（`MYSQL_*`/`SSH_*`）仅在无 `environments` 键的单环境配置下生效，优先级高于 `config.json`；如需临时覆盖单个变量，可在 `env` 字段中按需添加（详见[环境变量说明](#环境变量说明)）。\n\n### 多环境配置示例\n\n单个 MCP 服务器可同时注册**任意多套环境**（示例为 dev/uat/prod 三套；环境数量不限，环境名可用任意字母/数字/下划线组合），配置统一写在 `~/.mysql-mcp/config.json`（结构与密码均在同一文件）。\n\n**第一步：编写 `~/.mysql-mcp/config.json`**：\n\n```json\n{\n  \"defaultEnvironment\": \"dev\",\n  \"environments\": {\n    \"dev\": {\n      \"host\": \"192.168.1.100\",\n      \"port\": 3306,\n      \"user\": \"dev_user\",\n      \"password\": \"dev_password\",\n      \"database\": \"devdb\",\n      \"readOnly\": false,\n      \"maxRows\": 1000\n    },\n    \"uat\": {\n      \"host\": \"10.0.0.4\",\n      \"port\": 3306,\n      \"user\": \"uat_user\",\n      \"password\": \"uat_password\",\n      \"database\": \"uatdb\",\n      \"readOnly\": false,\n      \"maxRows\": 500\n    },\n    \"prod\": {\n      \"host\": \"10.0.0.5\",\n      \"port\": 3306,\n      \"user\": \"ai_readonly\",\n      \"password\": \"readonly_password\",\n      \"database\": \"proddb\",\n      \"readOnly\": true,\n      \"maxRows\": 100\n    }\n  }\n}\n```\n\n说明：dev/uat 与你的账号权限一致，AI 可自由执行 DDL/DML（按团队规范决定 uat 是否收紧）；prod 使用专用最小权限只读账号（见下方「生产环境只读加固」）并开启 `readOnly: true`（MCP 侧体验层：prod 禁用 mysql_execute / mysql_begin）。多环境格式下各环境的秘密仅来自本文件（`MYSQL_*`/`SSH_*` 环境变量不作用于环境定义）。\n\n**第二步：MCP 客户端配置零参数**：\n\n```json\n{\n  \"mcpServers\": {\n    \"mysql\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mysql2-mcp-server\"]\n    }\n  }\n}\n```\n\n配置完成后，AI 调用工具时通过 `environment` 参数选择环境：不传参数落到 `defaultEnvironment`；传入未注册的环境名会得到列出可用环境的错误，不会静默错位。每个工具的返回值都回显实际作用的环境名，方便你随时确认 AI 正在碰哪个环境。\n\n## 环境变量说明\n\n### MySQL 连接配置\n\n| 变量 | 说明 | 默认值 |\n|------|------|--------|\n| `MYSQL_HOST` | MySQL 服务器地址 | `localhost` |\n| `MYSQL_PORT` | MySQL 服务器端口 | `3306` |\n| `MYSQL_USER` | MySQL 用户名 | `root` |\n| `MYSQL_PASSWORD` | MySQL 密码 | - |\n| `MYSQL_DATABASE` | 默认数据库（可选） | - |\n| `READ_ONLY` | 是否启用只读模式（禁用 mysql_execute） | `false` |\n| `MAX_ROWS` | 查询结果最大行数，超出则中断结果集传输并标记截断 | `1000` |\n| `MYSQL_MCP_CONFIG_FILE` | 配置文件路径 | `~/.mysql-mcp/config.json` |\n\n> 多环境格式下 `MYSQL_*`/`SSH_*` 环境变量不作用于环境定义（环境仅来自 `config.json`）；它们仅在单环境（无 `environments` 键）下生效。\n\n### SSH 隧道配置\n\n| 变量 | 说明 | 默认值 |\n|------|------|--------|\n| `SSH_ENABLED` | 是否启用 SSH 隧道 | `false` |\n| `SSH_HOST` | SSH 服务器地址 | - |\n| `SSH_PORT` | SSH 服务器端口 | `22` |\n| `SSH_USERNAME` | SSH 用户名 | - |\n| `SSH_PASSWORD` | SSH 密码（与私钥二选一） | - |\n| `SSH_PRIVATE_KEY` | SSH 私钥内容（与密码二选一） | - |\n| `SSH_PASSPHRASE` | SSH 私钥密码（可选） | - |\n| `SSH_REMOTE_HOST` | 隧道目标 MySQL 地址 | `localhost` |\n| `SSH_REMOTE_PORT` | 隧道目标 MySQL 端口 | `3306` |\n\n## 可用工具\n\n所有工具均支持可选的 `environment` 参数路由到已注册环境（未传时使用 `defaultEnvironment`），成功返回均回显实际作用的环境名：\n\n### mysql_query\n\n执行 SQL 查询语句（SELECT/SHOW/DESCRIBE/EXPLAIN/WITH...SELECT），返回查询结果。\n\n**安全限制**:\n- 仅允许只读语句（SELECT、SHOW、DESCRIBE、EXPLAIN、WITH...SELECT）\n- 结果按该环境的 maxRows 流式截断：读到第 maxRows+1 行即中断传输（不会把全量结果读入内存）\n\n**截断提示**: 发生截断时，返回内容由两个块组成——第一个块是一句给 AI 的可见提示（`[结果已截断] 仅返回前 N 行…请用 WHERE/LIMIT 收窄范围…`），第二个块才是 JSON；JSON 中 `truncated` / `returnedRows` / `maxRows` 也排在最前面，确保模型在读到数据前就能看到截断状态。\n\n**参数**:\n- `sql`: SQL 查询语句\n- `environment`: 目标环境名（可选）\n\n**返回格式**:\n```json\n{\n  \"environment\": \"dev\",\n  \"truncated\": false,\n  \"returnedRows\": 10,\n  \"maxRows\": 1000,\n  \"rows\": [...]\n}\n```\n\n### mysql_execute\n\n执行 SQL 更新语句（INSERT、UPDATE、DELETE），返回影响的行数。\n\n**注意**: 当目标环境的 `readOnly: true` 时，此工具将被整体禁用（包括 SELECT 形式的语句，读数据请使用 `mysql_query`）。\n\n**参数**:\n- `sql`: SQL 执行语句\n- `environment`: 目标环境名（可选）\n\n### mysql_list_tables\n\n列出当前数据库中的所有表。\n\n**参数**: 无\n\n**返回格式**:\n```json\n{\n  \"tables\": [\"users\", \"orders\", \"products\"],\n  \"count\": 3\n}\n```\n\n### mysql_describe_table\n\n查看指定表的结构（列名、类型、是否可空、键信息、默认值等）。\n\n**参数**:\n- `table`: 要查看结构的表名\n\n**返回格式**:\n```json\n{\n  \"table\": \"users\",\n  \"columns\": [\n    {\n      \"Field\": \"id\",\n      \"Type\": \"int(11)\",\n      \"Null\": \"NO\",\n      \"Key\": \"PRI\",\n      \"Default\": null,\n      \"Extra\": \"auto_increment\"\n    }\n  ]\n}\n```\n\n### mysql_begin\n\n开始一个事务。事务期间的所有查询和更新操作都在同一连接上执行，保证原子性。事务状态按环境隔离，`mysql_commit` / `mysql_rollback` 需传相同 `environment`。\n\n**注意**: 仅直连模式支持事务，SSH 模式暂不支持。只读环境下不能开启事务。\n\n**参数**:\n- `environment`: 目标环境名（可选）\n\n### mysql_commit\n\n提交当前事务，将所有更改持久化。\n\n**参数**:\n- `environment`: 目标环境名（可选）\n\n### mysql_rollback\n\n回滚当前事务，撤销所有未提交的更改。\n\n**参数**:\n- `environment`: 目标环境名（可选）\n\n**事务使用示例**:\n1. 调用 `mysql_begin` 开始事务\n2. 执行多个 `mysql_query` / `mysql_execute` 操作\n3. 调用 `mysql_commit` 提交或 `mysql_rollback` 回滚\n\n## 使用场景\n\n1. **直连本地数据库**: 开发环境数据库可直接访问时使用\n2. **SSH 隧道连接**: 生产数据库需要通过跳板机访问时使用（dev 直连 + prod 走 SSH 隧道可共存于同一实例）\n3. **单实例多环境管理**: 一个 MCP 服务器同时注册任意多套环境（dev/uat/prod…），按环境独立权限与限行\n\n## 生产环境只读加固（推荐）\n\n如果 AI 只需要查询 prod，**最可靠的防护是在数据库侧创建最小权限只读账号**——这是唯一不可绕过的层，即使 MCP 进程本身被攻破，MySQL 服务器仍会拒绝写操作：\n\n```sql\n-- 创建仅能查询目标库的账号（host 限定为 MCP 运行来源地址，越窄越好）\nCREATE USER 'ai_readonly'@'<mcp来源host>' IDENTIFIED BY '<强密码>';\nGRANT SELECT, SHOW VIEW ON proddb.* TO 'ai_readonly'@'<mcp来源host>';\nFLUSH PRIVILEGES;\n```\n\n然后在多环境配置中让 prod 使用该账号，并开启 `readOnly: true`（MCP 侧体验层：提前拦截并给出友好错误，避免 AI 浪费轮次）。\n\n> **安全边界声明**：MCP 进程内的语句白名单与 readOnly 门禁是纵深防御与体验优化，**不是**安全边界——多语句、注释混淆等语句级绕过手段始终存在。不要仅依赖 `readOnly` 配置来保护生产数据；硬保证必须来自数据库侧的最小权限账号。\n\n## 注意事项\n\n- 配置文件含密码等敏感信息：请勿提交到版本控制，建议 Linux/macOS `chmod 600 ~/.mysql-mcp/config.json`\n- SSH 隧道模式适合连接内网或受保护的数据库；连接按需惰性建立，未被查询的环境不会建连\n- **默认非只读**：生产环境建议数据库侧只读账号 + `readOnly: true` 双层防护（见上方「生产环境只读加固」）\n- `mysql_query` 仅允许只读语句（SELECT/SHOW/DESCRIBE/EXPLAIN/WITH...SELECT），变更语句请使用 `mysql_execute`\n- 单连接配置（无 `environments` 键）自动映射为名为 `default` 的单一环境；连接按需惰性建立（启动零连接，首次调用时才报连接错误）\n\n## 贡献\n\n欢迎提交 Issue 和 Pull Request：\n\n1. Fork 本仓库并创建特性分支\n2. 提交前请确保 `npm test` 全部通过\n3. 提交 PR 并描述变更内容\n\nBug 反馈请使用 [Bug 报告模板](https://github.com/jcxy/mysql-mcp-server/issues/new?template=bug_report.yml)，功能建议请使用[功能建议模板](https://github.com/jcxy/mysql-mcp-server/issues/new?template=feature_request.yml)。\n\n## 发布流程（维护者）\n\n推送到 npm registry 由 GitHub Actions 自动完成：\n\n```bash\nnpm version minor   # 行为变更用 minor；纯修复用 patch\ngit push --tags\n```\n\n推送 `v*` 标签后会自动运行测试并发布到 npm（需在仓库 Secrets 中配置 `NPM_TOKEN`）。\n\n## 变更记录\n\n### v2.1.0\n\n**截断不再静默**：\n\n- 查询结果改为流式截断：读到第 maxRows+1 行即中断传输并销毁连接，不再先全量加载再切片（大表查询不再撑爆内存、不再等全表传完）\n- 截断时返回两个 content 块：首个块是一句给 AI 的可见提示（`[结果已截断] 仅返回前 N 行…请用 WHERE/LIMIT 收窄范围…`），JSON 在第二个块（此前只有 JSON 末尾的 `truncated: true`，模型常在读到它之前就被客户端裁掉，实际表现为静默截断）\n- JSON 中 `truncated` / `returnedRows` / `maxRows` 前置到 `rows` 之前\n- `mysql_query` / `mysql_list_tables` / `mysql_describe_table` 的工具描述声明各环境 maxRows 上限，便于 AI 主动用 WHERE/LIMIT 收窄\n- 事务内查询被截断时连接已销毁，事务随之作废，后续 `commit`/`rollback` 明确报「当前没有活跃的事务」\n- `MAX_ROWS` 默认值仍为 1000，不建议为省事而全局调大\n\n### v2.0.1\n\n- 文档：新增同类项目对比表与「只读拦截」演示；多环境示例扩展为 dev/uat/prod 三套，并明确环境数量不限、可任意命名\n- 渠道：新增 Smithery 一键安装（`smithery.yaml`）；补全 npm description 与 keywords 搜索元数据\n\n### v2.0.0\n\n**多环境支持 + 统一 JSON 配置**：\n\n- 单实例多环境：一个 MCP 服务器同时注册多个环境（`environments` + `defaultEnvironment`），所有工具支持可选 `environment` 参数显式路由，返回值回显实际作用环境名\n- 配置统一为 `~/.mysql-mcp/config.json`（纯 JSON，结构与密码同文件，路径可用 `MYSQL_MCP_CONFIG_FILE` 覆盖），MCP 客户端配置零参数\n- 按环境只读模式：readOnly 环境下 `mysql_execute` / `mysql_begin` 整体禁用；配套文档提供数据库侧最小权限只读账号的标准授权语句（唯一不可绕过的防护层）\n- 每环境独立连接池/SSH 隧道/事务状态，惰性建连（启动零连接，未被查询的环境不建连），单环境故障不影响其他环境\n- 启动期结构校验：非法环境名、多环境缺默认环境声明等配置错误直接拒启\n- 单环境支持环境变量配置（`MYSQL_*`/`SSH_*`，优先级：环境变量 > `config.json` > 默认值）\n\n### v1.3.0\n\n- 支持 npx 运行：`npx -y mysql2-mcp-server`，无需克隆仓库（新增 bin 入口）\n- `config.js` 改为可选：从当前工作目录加载，npx 场景下不存在也不影响启动\n- `package.json` 补全 npm 发布元数据（files 白名单、engines、repository 等）\n\n### v1.2.0\n\n**架构重构**：单文件拆分为模块化结构（`lib/config.js`、`lib/backend/`、`lib/tools.js`），安全强制（语句白名单、只读门控、结果截断）统一收敛到工具分派咽喉点，并新增 `npm test` 冒烟测试。\n\n**行为变更**：\n- 修复：事务提交/回滚失败时，未决事务的连接不再归还连接池（改为销毁），避免污染池中连接\n- 修复：事务连接异常断开时正确清理事务状态，消除竞态\n- `mysql_list_tables` / `mysql_describe_table` 结果也受 `MAX_ROWS` 截断\n- 事务工具成功消息改为 JSON 格式（`{\"status\": \"...\"}`）\n- SSH 错误消息改为中文并注明自动重连状态\n\n### v1.1.0\n\n- 安全机制：语句白名单、结果截断（`MAX_ROWS`）、只读模式（`READ_ONLY`）\n- SSH 断线自动重连（指数退避）\n- Schema 探索工具：`mysql_list_tables`、`mysql_describe_table`\n- 连接池与事务支持：`mysql_begin` / `mysql_commit` / `mysql_rollback`\n\n## License\n\nMIT","readmeFilename":"README.md"}