MCP 服务数据库客户端AI 应用【免费下载链接】mcp-server-mysqlA Model Context Protocol server that provides read-only access to MySQL databases. This server enables LLMs to inspect database schemas and execute read-only queries.项目地址https://gitcode.com/gh_mirrors/mc/mcp-server-mysql点击查看免费下载本文基于 mcp-server-mysql 仓库自带的 PROJECT_SETUP_GUIDE.md完整讲解如何为每个独立项目搭建SSH 隧道脚本 MCP 配置 自动 Hooks三位一体的远程 MySQL 接入方案读完你将掌握为多个项目分别建立唯一本地端口隧道、编写带密码输入钩子的.mcp.json、并让 Claude Code 启动/退出时自动启停隧道的完整流程同时结合仓库源码弄清每个ALLOW_*环境变量与MYSQL_DISABLE_READ_ONLY_TRANSACTIONS在底层是如何生效的。一、总览项目级数据库访问的三大组件该指南面向一个项目连接一个远程数据库的多项目场景。每个项目要打通 Claude Code 到 MySQL 的链路需要三个组件SSH Tunnel ScriptsSSH 隧道脚本建立到远程数据库的安全通道把远端3306端口映射到本地唯一端口如3307MCP ConfigurationMCP 配置在项目目录的.mcp.json中声明 MCP 服务器通过环境变量把数据库凭证注入 mcp-server-mysql 进程Hooks自动钩子在 Claude Code 启动时自动拉起隧道、退出时自动关闭隧道避免手动管理。整条链路为Claude Codestdio→node dist/index.js启动的 MCP 服务器 →127.0.0.1:33XX本地隧道端口→ SSH 隧道 → 远端 MySQL3306。示例项目配置表原文档给出了多项目并行时的典型端口规划端口必须全局唯一避免冲突项目端口SSH 服务器数据库位置project-a3307server1.example.com:1022db_project_a/path/to/project-aproject-b3308server1.example.com:1022db_project_b/path/to/project-bproject-c3309server2.example.com:1022db_project_c/path/to/project-cproject-d3310server1.example.com:1022db_project_d/path/to/project-d二、前置条件已构建的 MCP MySQL 服务器mcp-server-mysql需要支持MYSQL_DISABLE_READ_ONLY_TRANSACTIONS指南中用于允许CREATE TABLE等 DDL 操作后文会结合源码说明其底层行为通过npm run build或pnpm build构建。对应 package.json 中的build脚本为tsc shx chmod x dist/*.js产物入口是dist/index.jsmain字段亦指向它这也是指南.mcp.json中启动命令node dist/index.js的来源SSH 访问权限已配置 SSH 密钥~/.ssh/id_rsa已配置 known hosts本地 MySQL 客户端用于独立验证连接安装示例brew install mysql-client。三、步骤一创建 SSH 隧道脚本在项目目录下创建两个脚本启动脚本和停止脚本。start-tunnel-[project].sh#!/bin/bash # SSH Tunnel for [PROJECT] project LOCAL_PORT33XX # Use unique port (3307, 3308, 3309, etc.) REMOTE_SERVERyour.server.com # Your SSH server SSH_PORT1022 # SSH port (often 1022 or 22) SSH_USERyour_ssh_user # SSH username echo Starting SSH tunnel for [PROJECT] project... echo Local port: $LOCAL_PORT echo Remote server: $REMOTE_SERVER:$SSH_PORT echo User: $SSH_USER # Check if port is already in use if lsof -Pi :$LOCAL_PORT -sTCP:LISTEN -t /dev/null ; then echo ⚠️ Port $LOCAL_PORT already in use - tunnel may already be running exit 0 fi # Create the SSH tunnel ssh -f -N -L $LOCAL_PORT:localhost:3306 -p $SSH_PORT $SSH_USER$REMOTE_SERVER if [ $? -eq 0 ]; then sleep 2 if lsof -Pi :$LOCAL_PORT -sTCP:LISTEN -t /dev/null ; then echo ✅ [PROJECT] SSH tunnel created successfully on port $LOCAL_PORT else echo ❌ Tunnel creation failed exit 1 fi else echo ❌ Failed to create SSH tunnel exit 1 fi要点ssh -f -N -L $LOCAL_PORT:localhost:3306-f让 ssh 建好隧道后转入后台-N表示不执行远端命令-L把本地端口转发到隧道对端的localhost:3306即 SSH 服务器本机的 MySQL启动前先lsof -Pi :$LOCAL_PORT -sTCP:LISTEN -t检测端口占用若已监听则视为隧道已存在直接退出幂等设计方便 Hooks 重复触发建隧道后sleep 2再复查监听状态失败则exit 1。stop-tunnel-[project].sh#!/bin/bash # Stop SSH Tunnel for [PROJECT] project LOCAL_PORT33XX # Same port as in start script echo Stopping SSH tunnel for [PROJECT] project (port $LOCAL_PORT)... # Find and kill the tunnel process PID$(lsof -ti:$LOCAL_PORT) if [ -n $PID ]; then kill $PID echo ✅ [PROJECT] SSH tunnel stopped (PID: $PID) else echo ℹ️ No tunnel found running on port $LOCAL_PORT fi停止脚本的口径是谁在监听本地端口就杀掉谁用lsof -ti:$LOCAL_PORT取 PID 后kill。赋予执行权限chmod x start-tunnel-*.sh stop-tunnel-*.sh仓库内置脚本生产级的隧道管理参考mcp-server-mysql 仓库的 scripts/ 目录自带了一对功能等价、但更贴近生产环境的隧道脚本可作为指南模板的增强版参考scripts/start-tunnel-rds.sh面向经跳板机Bastion访问 RDS的更复杂拓扑核心转发命令为ssh -i $SSH_KEY -f -N -L $LOCAL_PORT:$RDS_ENDPOINT:$RDS_PORT -p $BASTION_PORT $BASTION_USER_HOST见 第 63 行即在跳板机上把流量转发到 VPC 内的RDS_ENDPOINT:RDS_PORT而不是跳板机本机的 3306该脚本开头用set -euo pipefail并强制校验BASTION_HOST、RDS_ENDPOINT、SSH_KEY三个必填项第 19-47 行所有参数均可通过环境变量覆盖LOCAL_PORT、BASTION_USER等比指南模板中硬编码变量更便于多项目复用scripts/stop-tunnel-rds.sh除按端口杀进程外还会在kill后复查监听状态未释放时提示kill -9 $(lsof -ti :$LOCAL_PORT)手动兜底第 19-31 行scripts/tunnel-config.example示例配置文件约定把LOCAL_PORT、BASTION_*、RDS_*、SSH_KEY写入tunnel-config.sh后source再启动隧道隧道建立后在 MCP 配置中使用MYSQL_HOST127.0.0.1MYSQL_PORTLOCAL_PORT。如果你的数据库就在 SSH 服务器本机直接用指南模板如果是经跳板机访问 VPC/RDS 实例建议对照仓库内脚本改造。四、步骤二创建 MCP 配置.mcp.json在项目目录创建.mcp.json指南给出的完整模板如下{ hooks: { claude_start: { command: ./start-tunnel-[project].sh, background: true, description: Start SSH tunnel for [PROJECT] database }, claude_stop: { command: ./stop-tunnel-[project].sh, background: false, description: Stop SSH tunnel for [PROJECT] database } }, inputs: [ { type: promptString, id: mysql-password-[project], description: MySQL Password for [PROJECT] Database, password: true, default: your_password_here } ], servers: { [project]-mysql-server: { type: stdio, command: bash, args: [-c, cd /path/to/mcp-server-mysql node dist/index.js], env: { MYSQL_HOST: 127.0.0.1, MYSQL_PORT: 33XX, MYSQL_USER: your_db_user, MYSQL_PASS: ${input:mysql-password-[project]}, MYSQL_DB: your_database_name, ALLOW_INSERT_OPERATION: true, ALLOW_UPDATE_OPERATION: true, ALLOW_DELETE_OPERATION: true, ALLOW_DDL_OPERATION: true, MYSQL_DISABLE_READ_ONLY_TRANSACTIONS: true } } } }各部分作用hooksclaude_start在 Claude Code 启动时以后台方式background: true执行启动脚本claude_stop在退出时前台执行停止脚本。这样隧道生命周期与 Claude 会话绑定无需人工干预inputs声明一个promptString类型的密码输入password: true表示以密文提示输入服务器env中用${input:mysql-password-[project]}占位符引用避免明文散落在服务器配置块里但default值仍会写在文件中安全注意事项见第八节servers声明一个stdio类型的 MCP 服务器。commandargs用bash -c cd /path/to/mcp-server-mysql node dist/index.js的方式切到已构建的仓库目录再启动服务器——这解释了前置条件中必须先npm run build的原因启动的是编译产物dist/index.jsenv即 mcp-server-mysql 的数据库连接与权限开关MYSQL_HOST/MYSQL_PORT指向隧道本地端MYSQL_USER/MYSQL_PASS/MYSQL_DB为数据库凭证。源码印证这些环境变量在服务器内部如何生效结合仓库源码可以确认上述env参数的真实行为也解释了指南为何强调写操作参数1. 写操作开关是严格字符串匹配。src/config/index.ts 中// Write operation flags (global defaults) export const ALLOW_INSERT_OPERATION process.env.ALLOW_INSERT_OPERATION true; export const ALLOW_UPDATE_OPERATION process.env.ALLOW_UPDATE_OPERATION true; export const ALLOW_DELETE_OPERATION process.env.ALLOW_DELETE_OPERATION true; export const ALLOW_DDL_OPERATION process.env.ALLOW_DDL_OPERATION true; // Transaction mode control export const MYSQL_DISABLE_READ_ONLY_TRANSACTIONS process.env.MYSQL_DISABLE_READ_ONLY_TRANSACTIONS true;即只有值恰好为字符串true才生效默认全部为false——这与 README.md 中write operations opt-in via env flags的描述一致。入口文件 index.ts 会据此计算isReadOnly并写进mysql_query工具的readOnlyHint/destructiveHint注解供 LLM 客户端理解该工具是否具有破坏性。2.MYSQL_DISABLE_READ_ONLY_TRANSACTIONS控制会话级只读事务。这是指南特别点名必须支持的参数原因在于 mcp-server-mysql 的只读查询路径 src/db/index.tsconnection await pool.getConnection(); // Set read-only mode (unless disabled via environment variable) if (!MYSQL_DISABLE_READ_ONLY_TRANSACTIONS) { await connection.query(SET SESSION TRANSACTION READ ONLY); } else { log(info, Read-only transactions disabled via MYSQL_DISABLE_READ_ONLY_TRANSACTIONStrue); } await connection.beginTransaction();若不禁用只读查询会先执行SET SESSION TRANSACTION READ ONLY再开事务事务结束回滚后恢复READ WRITE。指南的验证流程包含CREATE TABLE/INSERT/DROP TABLE见第六节这些写操作需要关闭该会话级保护故模板中显式设置MYSQL_DISABLE_READ_ONLY_TRANSACTIONS: true。3. 写操作还有第二道闸门按 schema 的权限检查。src/db/permissions.ts 中每个isXxxAllowedForSchema(schema)函数先查SCHEMA_*_PERMISSIONS的按库覆盖项未命中才回落到全局ALLOW_*_OPERATION开关执行层在 src/db/index.ts 先用getQueryTypes解析出语句类型再逐一校验例如if (isDDLOperation !isDDLAllowedForSchema(schema)) { log(error, DDL operations are not allowed for schema ${schema || default}...); ... } // For write operations that are allowed, use executeWriteQuery if ( (isInsertOperation isInsertAllowedForSchema(schema)) || (isUpdateOperation isUpdateAllowedForSchema(schema)) || (isDeleteOperation isDeleteAllowedForSchema(schema)) || (isDDLOperation isDDLAllowedForSchema(schema)) ) { return executeWriteQuery(sql); }从源码结构看即使四个ALLOW_*全开也可以再用SCHEMA_INSERT_PERMISSIONS、SCHEMA_DDL_PERMISSIONS等变量做按库细粒度控制这是指南模板未展开、但同一仓库支持的进阶能力。4. 连接池与默认值。连接参数在 src/config/index.ts 的mcpConfig.mysql中组装MYSQL_HOST缺省127.0.0.1、MYSQL_PORT缺省3306、MYSQL_USER缺省root、密码缺省空串连接池固定connectionLimit: 10并可由MYSQL_CONNECT_TIMEOUT调整超时默认 10000ms。指南中所有必填env项均能在此找到对应解析逻辑。5. 启动即做连接自检。服务器入口 index.ts 在连接 stdio 传输前会先getPool()并取一个连接做测试失败即safeExit(1)第 561-567 行 中非 remote 模式则使用StdioServerTransport启动。因此隧道没起来导致服务器起不来/连不上会直接体现在 MCP 服务器的报错里这也是第九节排障顺序先查隧道、再查 MCP的依据。五、步骤三端口映射规划为每个项目选择唯一本地端口避免多个隧道互相抢占端口区间用途3307第一个项目3308第二个项目3309第三个项目3310第四个项目3311后续项目六、项目文件结构按指南约定每个项目的目录应长这样/path/to/your/project/ ├── .mcp.json # MCP 配置 ├── start-tunnel-[project].sh # 启动 SSH 隧道脚本 ├── stop-tunnel-[project].sh # 停止 SSH 隧道脚本 └── ... (your project files)七、两个完整配置示例示例 1部署在 example.com 上的项目如 project-a/b/d完整.mcp.json隧道端口3311{ hooks: { claude_start: { command: ./start-tunnel-myproject.sh, background: true, description: Start SSH tunnel for myproject database }, claude_stop: { command: ./stop-tunnel-myproject.sh, background: false, description: Stop SSH tunnel for myproject database } }, inputs: [ { type: promptString, id: mysql-password-myproject, description: MySQL Password for myproject Database, password: true, default: my_secure_password } ], servers: { myproject-mysql-server: { type: stdio, command: bash, args: [-c, cd /path/to/mcp-server-mysql node dist/index.js], env: { MYSQL_HOST: 127.0.0.1, MYSQL_PORT: 3311, MYSQL_USER: db_myproject, MYSQL_PASS: ${input:mysql-password-myproject}, MYSQL_DB: db_myproject, ALLOW_INSERT_OPERATION: true, ALLOW_UPDATE_OPERATION: true, ALLOW_DELETE_OPERATION: true, ALLOW_DDL_OPERATION: true, MYSQL_DISABLE_READ_ONLY_TRANSACTIONS: true } } } }示例 2部署在另一台服务器上的项目如 project-c只需修改启动脚本中的目标地址与 SSH 端口# start-tunnel-myproject.sh LOCAL_PORT3312 REMOTE_SERVERserver2.example.com SSH_PORT22 # Standard SSH port SSH_USERmyuser其余停止脚本端口、.mcp.json中的MYSQL_PORT与MYSQL_DB与示例 1 同构替换即可。八、测试你的配置1. 手动测试 SSH 隧道# 手动启动隧道 ./start-tunnel-[project].sh # 检查端口是否在监听 lsof -i :33XX # 停止隧道 ./stop-tunnel-[project].sh2. 测试数据库连接# 通过隧道测试连接 mysql -h 127.0.0.1 -P 33XX -u db_user -ppassword -D database_name -e SELECT Connection OK as status;此步骤绕过 MCP 直接验证隧道 凭证 数据库名三要素能隔离问题来源。3. 测试 Claude 集成# 进入项目目录 cd /path/to/your/project # 启动 Claude应自动拉起隧道 claude # 查看 MCP 服务器状态 /mcp # 退出 Claude应自动停止隧道 # 按两次 CtrlC4. 测试 MCP 服务器操作进入 Claude 后通过mysql_query工具执行一套 DDL/DML 往返验证这也是指南要求MYSQL_DISABLE_READ_ONLY_TRANSACTIONS的原因CREATE TABLE test_table ( id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(100) ); INSERT INTO test_table (name) VALUES (Test); SELECT * FROM test_table; DROP TABLE test_table;从源码看CREATE/ALTER/DROP/TRUNCATE会被识别为 DDL见 src/db/index.tsINSERT识别为写操作分别对应第四节的isDDLAllowedForSchema/isInsertAllowedForSchema检查全部放行后走executeWriteQuery。九、故障排查1. SSH 隧道启动失败检查 SSH 密钥确认~/.ssh/id_rsa存在且权限正确600手动测试 SSHssh -p 1022 userserver.com检查端口占用lsof -i :33XX。2. 数据库连接失败确认隧道在运行lsof -i :33XX核对凭证直接用 mysql 客户端测试确认数据库存在SHOW DATABASES;。3. MCP 服务器无法连接确认已构建ls /path/to/mcp-server-mysql/dist/Node.js 版本node --version指南建议 18 或 20仓库 README.md 要求 Node.js v20查看日志claude --debug。4. Hooks 不生效检查脚本权限ls -la *.sh必须可执行核对脚本路径.mcp.json中用相对路径./script.sh手动运行脚本直接执行 start/stop 脚本定位问题。5. 端口冲突杀掉占用进程kill $(lsof -ti:33XX)更换端口同步修改两个脚本和.mcp.json三处。常用调试命令# 查看所有 SSH 隧道 ps aux | grep ssh | grep -E 3307|3308|3309|3310 # 查看所有监听端口 lsof -i -P | grep LISTEN | grep -E 3307|3308|3309|3310 # 直接测试 MCP 服务器 cd /path/to/mcp-server-mysql MYSQL_HOST127.0.0.1 MYSQL_PORT33XX MYSQL_USERuser MYSQL_PASSpass MYSQL_DBdb node dist/index.js # 查看 Claude 日志 claude --debug 21 | grep -i mcp其中直接测试 MCP 服务器一条与源码行为吻合服务器启动时会立即尝试数据库连接并打印配置摘要index.ts 中的MySQL Configuration日志、第 374-379 行 的连接测试连接失败会直接safeExit(1)方便在无 Claude 环境下复现问题。十、安全注意事项密码存储.mcp.json中inputs的default密码是明文可见的。指南建议改用环境变量注入去掉default每次手动输入结合密码管理器。SSH 密钥权限设为 600设置密钥口令以加强保护定期轮换。端口安全本地端口3307–3310仅在 localhost 上监听不对外暴露。十一、新项目快速上线清单每接入一个新项目按顺序完成选择唯一本地端口3311、3312 等创建start-tunnel-[project].sh填入正确的服务器信息创建stop-tunnel-[project].sh端口与启动脚本一致赋予执行权限chmod x *.sh创建.mcp.jsonstart/stop 脚本的 Hooks密码输入项MCP 服务器配置手动测试 SSH 隧道测试数据库连接用claude命令实测确认自动启停隧道生效十二、小结与延伸阅读这套隧道脚本 .mcp.json Hooks模式把远程 MySQL 的接入成本压缩为每项目三个文件并借 mcp-server-mysql 的ALLOW_*权限开关与MYSQL_DISABLE_READ_ONLY_TRANSACTIONS事务控制实现最小权限的写操作。进一步可结合仓库文档深入docs/CONFIGURATION.md全部环境变量含SCHEMA_*_PERMISSIONS按库权限、SSL/mTLS、多库模式、docs/INSTALLATION.md安装方式、docs/TROUBLESHOOTING.md故障排查、README-MULTI-DB.md多数据库模式以及仓库自带的 scripts/start-tunnel-rds.sh、scripts/stop-tunnel-rds.sh、scripts/tunnel-config.example 作为跳板机场景的脚本范本。赞分享MCP 服务数据库客户端AI 应用【免费下载链接】mcp-server-mysqlA Model Context Protocol server that provides read-only access to MySQL databases. This server enables LLMs to inspect database schemas and execute read-only queries.项目地址https://gitcode.com/gh_mirrors/mc/mcp-server-mysql点击查看免费下载相关推荐claude-skills 实战Atlassian MCP Server 完整配置指南Jira Confluence 接入 Claude Codeclaude skills 实战Atlassian MCP Server 完整配置指南Jira Confluence 接入 Claude Code 本AI 技能AI 插件后端前端DevOpsMetabase SSH 隧道SSH Tunneling数据库连接完全指南Metabase SSH 隧道SSH Tunneling数据库连接完全指南 Metabase 通过内置的 SSH 客户端建立到堡垒机Bastion Hos数据分析数据可视化后端数据库客户端企业应用Klavis 仓库中的 GitHub MCP Server在 Claude Code 与 Claude Desktop 中接入的完整实战指南Klavis 仓库中的 GitHub MCP Server在 Claude Code 与 Claude Desktop 中接入的完整实战指南 在 KlavisAI 应用LLM 网关MCP 服务工具调用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考