[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-benborla--mcp-server-mysql":3,"tool-benborla--mcp-server-mysql":65},[4,18,28,37,45,57],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":24,"last_commit_at":25,"category_tags":26,"status":17},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[13,27],"插件",{"id":29,"name":30,"github_repo":31,"description_zh":32,"stars":33,"difficulty_score":34,"last_commit_at":35,"category_tags":36,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,2,"2026-04-10T01:20:03",[27,13,15,14],{"id":38,"name":39,"github_repo":40,"description_zh":41,"stars":42,"difficulty_score":34,"last_commit_at":43,"category_tags":44,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[27,14],{"id":46,"name":47,"github_repo":48,"description_zh":49,"stars":50,"difficulty_score":34,"last_commit_at":51,"category_tags":52,"status":17},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",85092,"2026-04-10T11:13:16",[15,16,53,27,13,54,55,14,56],"视频","其他","语言模型","音频",{"id":58,"name":59,"github_repo":60,"description_zh":61,"stars":62,"difficulty_score":24,"last_commit_at":63,"category_tags":64,"status":17},5784,"funNLP","fighting41love\u002FfunNLP","funNLP 是一个专为中文自然语言处理（NLP）打造的超级资源库，被誉为\"NLP 民工的乐园”。它并非单一的软件工具，而是一个汇集了海量开源项目、数据集、预训练模型和实用代码的综合性平台。\n\n面对中文 NLP 领域资源分散、入门门槛高以及特定场景数据匮乏的痛点，funNLP 提供了“一站式”解决方案。这里不仅涵盖了分词、命名实体识别、情感分析、文本摘要等基础任务的标准工具，还独特地收录了丰富的垂直领域资源，如法律、医疗、金融行业的专用词库与数据集，甚至包含古诗词生成、歌词创作等趣味应用。其核心亮点在于极高的全面性与实用性，从基础的字典词典到前沿的 BERT、GPT-2 模型代码，再到高质量的标注数据和竞赛方案，应有尽有。\n\n无论是刚刚踏入 NLP 领域的学生、需要快速验证想法的算法工程师，还是从事人工智能研究的学者，都能在这里找到急需的“武器弹药”。对于开发者而言，它能大幅减少寻找数据和复现模型的时间；对于研究者，它提供了丰富的基准测试资源和前沿技术参考。funNLP 以开放共享的精神，极大地降低了中文自然语言处理的开发与研究成本，是中文 AI 社区不可或缺的宝藏仓库。",79857,"2026-04-08T20:11:31",[55,16,54],{"id":66,"github_repo":67,"name":68,"description_en":69,"description_zh":70,"ai_summary_zh":70,"readme_en":71,"readme_zh":72,"quickstart_zh":73,"use_case_zh":74,"hero_image_url":75,"owner_login":76,"owner_name":77,"owner_avatar_url":78,"owner_bio":79,"owner_company":80,"owner_location":81,"owner_email":82,"owner_twitter":80,"owner_website":83,"owner_url":84,"languages":85,"stars":101,"forks":102,"last_commit_at":103,"license":104,"difficulty_score":34,"env_os":105,"env_gpu":106,"env_ram":105,"env_deps":107,"category_tags":113,"github_topics":80,"view_count":34,"oss_zip_url":80,"oss_zip_packed_at":80,"status":17,"created_at":114,"updated_at":115,"faqs":116,"releases":144},8356,"benborla\u002Fmcp-server-mysql","mcp-server-mysql","A 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.","mcp-server-mysql 是一款基于 Node.js 开发的开源工具，旨在让大语言模型（如 Claude）安全地连接并操作 MySQL 数据库。它遵循模型上下文协议（MCP），使 AI 能够直接 inspect 数据库架构、执行只读查询，甚至在配置允许时进行数据写入操作。\n\n该工具主要解决了 AI 在开发过程中无法直接访问真实数据库环境的痛点。通过它，开发者可以让 AI 助手理解现有的表结构，辅助编写复杂的 SQL 语句，或自动检查数据一致性，从而大幅提升数据库相关的开发效率与准确性。\n\nmcp-server-mysql 特别适合后端开发者、全栈工程师以及需要频繁与数据库交互的 AI 应用构建者使用。无论是本地调试还是远程协作，它都能提供流畅的体验。\n\n其独特的技术亮点包括对 SSH 隧道的原生支持，这意味着它可以安全地连接位于远程服务器上的数据库，而无需暴露端口到公网。此外，该版本专门针对 Claude Code CLI 进行了优化，支持隧道自动启停管理，并允许灵活配置多项目环境与细粒度的权限控制（如单独开启插入或更新权限），在保障数据安全的前提下提供了极高的灵活性。","# MCP Server for MySQL - Claude Code Edition\n\n> **🚀 This is a modified version optimized for Claude Code with SSH tunnel support**  \n> **Original Author:** [@benborla29](https:\u002F\u002Fgithub.com\u002Fbenborla)  \n> **Original Repository:** [https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql](https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql)  \n> **License:** MIT  \n\n## MCP Server for MySQL based on NodeJS\n\n[![Trust Score](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fbenborla_mcp-server-mysql_readme_5dfccc754b71.png)](https:\u002F\u002Farchestra.ai\u002Fmcp-catalog\u002Fbenborla__mcp-server-mysql)\n\n### Key Features of This Fork\n\n- ✅ **Claude Code Integration** - Optimized for use with Anthropic's Claude Code CLI\n- ✅ **SSH Tunnel Support** - Built-in support for SSH tunnels to remote databases\n- ✅ **Auto-start\u002Fstop Hooks** - Automatic tunnel management with Claude start\u002Fstop\n- ✅ **DDL Operations** - Added `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS` for CREATE TABLE support\n- ✅ **Multi-Project Setup** - Easy configuration for multiple projects with different databases\n\n### Quick Start for Claude Code Users\n\n1. **Read the Setup Guide**: See [PROJECT_SETUP_GUIDE.md](PROJECT_SETUP_GUIDE.md) for detailed instructions\n2. **Configure SSH Tunnels**: Set up automatic SSH tunnels for remote databases\n3. **Use with Claude**: Integrated MCP server works seamlessly with Claude Code\n\nA Model Context Protocol server that provides access to MySQL databases through SSH tunnels. This server enables Claude and other LLMs to inspect database schemas and execute SQL queries securely.\n\n## Table of Contents\n\n- [Requirements](#requirements)\n- [Installation](#installation)\n  - [Smithery](#using-smithery)\n  - [Clone to Local Repository](#running-from-local-repository)\n  - [Remote mode](#run-in-remote-mode)\n- [Components](#components)\n- [Configuration](#configuration)\n- [Environment Variables](#environment-variables)\n- [Multi-DB Mode](#multi-db-mode)\n- [Schema-Specific Permissions](#schema-specific-permissions)\n- [Testing](#testing)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Requirements\n\n- Node.js v20 or higher\n- MySQL 5.7 or higher (MySQL 8.0+ recommended)\n- MySQL user with appropriate permissions for the operations you need\n- For write operations: MySQL user with INSERT, UPDATE, and\u002For DELETE privileges\n\n## Installation\n\n### Using Smithery\n\nThere are several ways to install and configure the MCP server but the most common would be checking this website [https:\u002F\u002Fsmithery.ai\u002Fserver\u002F@benborla29\u002Fmcp-server-mysql](https:\u002F\u002Fsmithery.ai\u002Fserver\u002F@benborla29\u002Fmcp-server-mysql)\n\n### Cursor\n\nFor Cursor IDE, you can install this MCP server with the following command in your project:\n\n1. Visit [https:\u002F\u002Fsmithery.ai\u002Fserver\u002F@benborla29\u002Fmcp-server-mysql](https:\u002F\u002Fsmithery.ai\u002Fserver\u002F@benborla29\u002Fmcp-server-mysql)\n2. Follow the instruction for Cursor\n\nMCP Get provides a centralized registry of MCP servers and simplifies the installation process.\n\n### Codex CLI\n\nCodex CLI installation is similar to Claude Code below\n\n```bash\ncodex mcp add mcp_server_mysql \\\n  --env MYSQL_HOST=\"127.0.0.1\" \\\n  --env MYSQL_PORT=\"3306\" \\\n  --env MYSQL_USER=\"root\" \\\n  --env MYSQL_PASS=\"your_password\" \\\n  --env MYSQL_DB=\"your_database\" \\\n  --env ALLOW_INSERT_OPERATION=\"false\" \\\n  --env ALLOW_UPDATE_OPERATION=\"false\" \\\n  --env ALLOW_DELETE_OPERATION=\"false\" \\\n  -- npx -y @benborla29\u002Fmcp-server-mysql\n```\n\n### Claude Code\n\n#### Option 1: Import from Claude Desktop (Recommended if already configured)\n\nIf you already have this MCP server configured in Claude Desktop, you can import it automatically:\n\n```bash\nclaude mcp add-from-claude-desktop\n```\n\nThis will show an interactive dialog where you can select your `mcp_server_mysql` server to import with all existing configuration.\n\n#### Option 2: Manual Configuration\n\n**Using NPM\u002FPNPM Global Installation:**\n\nFirst, install the package globally:\n\n```bash\n# Using npm\nnpm install -g @benborla29\u002Fmcp-server-mysql\n\n# Using pnpm\npnpm add -g @benborla29\u002Fmcp-server-mysql\n```\n\nThen add the server to Claude Code:\n\n```bash\nclaude mcp add mcp_server_mysql \\\n  -e MYSQL_HOST=\"127.0.0.1\" \\\n  -e MYSQL_PORT=\"3306\" \\\n  -e MYSQL_USER=\"root\" \\\n  -e MYSQL_PASS=\"your_password\" \\\n  -e MYSQL_DB=\"your_database\" \\\n  -e ALLOW_INSERT_OPERATION=\"false\" \\\n  -e ALLOW_UPDATE_OPERATION=\"false\" \\\n  -e ALLOW_DELETE_OPERATION=\"false\" \\\n  -- npx @benborla29\u002Fmcp-server-mysql\n```\n\n**Using Local Repository (for development):**\n\nIf you're running from a cloned repository:\n\n```bash\nclaude mcp add mcp_server_mysql \\\n  -e MYSQL_HOST=\"127.0.0.1\" \\\n  -e MYSQL_PORT=\"3306\" \\\n  -e MYSQL_USER=\"root\" \\\n  -e MYSQL_PASS=\"your_password\" \\\n  -e MYSQL_DB=\"your_database\" \\\n  -e ALLOW_INSERT_OPERATION=\"false\" \\\n  -e ALLOW_UPDATE_OPERATION=\"false\" \\\n  -e ALLOW_DELETE_OPERATION=\"false\" \\\n  -e PATH=\"\u002Fpath\u002Fto\u002Fnode\u002Fbin:\u002Fusr\u002Fbin:\u002Fbin\" \\\n  -e NODE_PATH=\"\u002Fpath\u002Fto\u002Fnode\u002Flib\u002Fnode_modules\" \\\n  -- \u002Fpath\u002Fto\u002Fnode \u002Ffull\u002Fpath\u002Fto\u002Fmcp-server-mysql\u002Fdist\u002Findex.js\n```\n\nReplace:\n\n- `\u002Fpath\u002Fto\u002Fnode` with your Node.js binary path (find with `which node`)\n- `\u002Ffull\u002Fpath\u002Fto\u002Fmcp-server-mysql` with the full path to your cloned repository\n- Update MySQL credentials to match your environment\n\n**Using Unix Socket Connection:**\n\nFor local MySQL instances using Unix sockets:\n\n```bash\nclaude mcp add mcp_server_mysql \\\n  -e MYSQL_SOCKET_PATH=\"\u002Ftmp\u002Fmysql.sock\" \\\n  -e MYSQL_USER=\"root\" \\\n  -e MYSQL_PASS=\"your_password\" \\\n  -e MYSQL_DB=\"your_database\" \\\n  -e ALLOW_INSERT_OPERATION=\"false\" \\\n  -e ALLOW_UPDATE_OPERATION=\"false\" \\\n  -e ALLOW_DELETE_OPERATION=\"false\" \\\n  -- npx @benborla29\u002Fmcp-server-mysql\n```\n\n#### Choosing the Right Scope\n\nConsider which scope to use based on your needs:\n\n```bash\n# Local scope (default) - only available in current project\nclaude mcp add mcp_server_mysql [options...]\n\n# User scope - available across all your projects\nclaude mcp add mcp_server_mysql -s user [options...]\n\n# Project scope - shared with team members via .mcp.json\nclaude mcp add mcp_server_mysql -s project [options...]\n```\n\nFor database servers with credentials, **local** or **user** scope is recommended to keep credentials private.\n\n#### Verification\n\nAfter adding the server, verify it's configured correctly:\n\n```bash\n# List all configured servers\nclaude mcp list\n\n# Get details for your MySQL server\nclaude mcp get mcp_server_mysql\n\n# Check server status within Claude Code\n\u002Fmcp\n```\n\n#### Multi-Database Configuration\n\nFor multi-database mode, omit the `MYSQL_DB` environment variable:\n\n```bash\nclaude mcp add mcp_server_mysql_multi \\\n  -e MYSQL_HOST=\"127.0.0.1\" \\\n  -e MYSQL_PORT=\"3306\" \\\n  -e MYSQL_USER=\"root\" \\\n  -e MYSQL_PASS=\"your_password\" \\\n  -e MULTI_DB_WRITE_MODE=\"false\" \\\n  -- npx @benborla29\u002Fmcp-server-mysql\n```\n\n#### Advanced Configuration\n\nFor advanced features, add additional environment variables:\n\n```bash\nclaude mcp add mcp_server_mysql \\\n  -e MYSQL_HOST=\"127.0.0.1\" \\\n  -e MYSQL_PORT=\"3306\" \\\n  -e MYSQL_USER=\"root\" \\\n  -e MYSQL_PASS=\"your_password\" \\\n  -e MYSQL_DB=\"your_database\" \\\n  -e MYSQL_POOL_SIZE=\"10\" \\\n  -e MYSQL_QUERY_TIMEOUT=\"30000\" \\\n  -e MYSQL_CACHE_TTL=\"60000\" \\\n  -e MYSQL_RATE_LIMIT=\"100\" \\\n  -e MYSQL_SSL=\"true\" \\\n  -e ALLOW_INSERT_OPERATION=\"false\" \\\n  -e ALLOW_UPDATE_OPERATION=\"false\" \\\n  -e ALLOW_DELETE_OPERATION=\"false\" \\\n  -e MYSQL_ENABLE_LOGGING=\"true\" \\\n  -- npx @benborla29\u002Fmcp-server-mysql\n```\n\n#### Troubleshooting Claude Code Setup\n\n1. **Server Connection Issues**: Use `\u002Fmcp` command in Claude Code to check server status and authenticate if needed.\n\n2. **Path Issues**: If using a local repository, ensure Node.js paths are correctly set:\n\n   ```bash\n   # Find your Node.js path\n   which node\n\n   # For PATH environment variable\n   echo \"$(which node)\u002F..\u002F\"\n\n   # For NODE_PATH environment variable\n   echo \"$(which node)\u002F..\u002F..\u002Flib\u002Fnode_modules\"\n   ```\n\n3. **Permission Errors**: Ensure your MySQL user has appropriate permissions for the operations you've enabled.\n\n4. **Server Not Starting**: Check Claude Code logs or run the server directly to debug:\n\n   ```bash\n   # Test the server directly\n   npx @benborla29\u002Fmcp-server-mysql\n   ```\n\n### Using NPM\u002FPNPM\n\nFor manual installation:\n\n```bash\n# Using npm\nnpm install -g @benborla29\u002Fmcp-server-mysql\n\n# Using pnpm\npnpm add -g @benborla29\u002Fmcp-server-mysql\n```\n\nAfter manual installation, you'll need to configure your LLM application to use the MCP server (see Configuration section below).\n\n### Running from Local Repository\n\nIf you want to clone and run this MCP server directly from the source code, follow these steps:\n\n1. **Clone the repository**\n\n   ```bash\n   git clone https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql.git\n   cd mcp-server-mysql\n   ```\n\n2. **Install dependencies**\n\n   ```bash\n   npm install\n   # or\n   pnpm install\n   ```\n\n3. **Build the project**\n\n   ```bash\n   npm run build\n   # or\n   pnpm run build\n   ```\n\n4. **Configure Claude Desktop**\n\n   Add the following to your Claude Desktop configuration file (`claude_desktop_config.json`):\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"mcp_server_mysql\": {\n         \"command\": \"\u002Fpath\u002Fto\u002Fnode\",\n         \"args\": [\n           \"\u002Ffull\u002Fpath\u002Fto\u002Fmcp-server-mysql\u002Fdist\u002Findex.js\"\n         ],\n         \"env\": {\n           \"MYSQL_HOST\": \"127.0.0.1\",\n           \"MYSQL_PORT\": \"3306\",\n           \"MYSQL_USER\": \"root\",\n           \"MYSQL_PASS\": \"your_password\",\n           \"MYSQL_DB\": \"your_database\",\n           \"ALLOW_INSERT_OPERATION\": \"false\",\n           \"ALLOW_UPDATE_OPERATION\": \"false\",\n           \"ALLOW_DELETE_OPERATION\": \"false\",\n           \"PATH\": \"\u002Fpath\u002Fto\u002Fnode\u002Fbin:\u002Fusr\u002Fbin:\u002Fbin\", \u002F\u002F \u003C--- Important to add the following, run in your terminal `echo \"$(which node)\u002F..\u002F\"` to get the path\n           \"NODE_PATH\": \"\u002Fpath\u002Fto\u002Fnode\u002Flib\u002Fnode_modules\" \u002F\u002F \u003C--- Important to add the following, run in your terminal `echo \"$(which node)\u002F..\u002F..\u002Flib\u002Fnode_modules\"`\n         }\n       }\n     }\n   }\n   ```\n\n   Replace:\n   - `\u002Fpath\u002Fto\u002Fnode` with the full path to your Node.js binary (find it with `which node`)\n   - `\u002Ffull\u002Fpath\u002Fto\u002Fmcp-server-mysql` with the full path to where you cloned the repository\n   - Set the MySQL credentials to match your environment\n\n5. **Test the server**\n\n   ```bash\n   # Run the server directly to test\n   node dist\u002Findex.js\n   ```\n\n   If it connects to MySQL successfully, you're ready to use it with Claude Desktop.\n\n### Run in remote mode\n\nTo run in remote mode, you'll need to provide [environment variables](https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql?tab=readme-ov-file#environment-variables) to the npx script.\n\n1. Create env file in preferred directory\n\n   ```bash\n   # create .env file\n   touch .env\n   ```\n\n2. Copy-paste [example file](https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql\u002Fblob\u002Fmain\u002F.env) from this repository\n3. Set the MySQL credentials to match your environment\n4. Set `IS_REMOTE_MCP=true`\n5. Set `REMOTE_SECRET_KEY` to a secure string.\n6. Provide custom `PORT` if needed. Default is 3000.\n7. Load variables in current session:\n\n   ```bash\n   source .env\n   ```\n\n8. Run the server\n\n   ```bash\n   npx @benborla29\u002Fmcp-server-mysql\n   ```\n\n9. Configure your agent to connect to the MCP with the next configuration:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"mysql\": {\n         \"url\": \"http:\u002F\u002Fyour-host:3000\u002Fmcp\",\n         \"type\": \"streamableHttp\",\n         \"headers\": {\n           \"Authorization\": \"Bearer \u003CREMOTE_SECRET_KEY>\"\n         }\n       }\n     }\n   }\n   ```\n\n## Components\n\n### Tools\n\n- **mysql_query**\n  - Execute SQL queries against the connected database\n  - Input: `sql` (string): The SQL query to execute\n  - By default, limited to READ ONLY operations\n  - Optional write operations (when enabled via configuration):\n    - INSERT: Add new data to tables (requires `ALLOW_INSERT_OPERATION=true`)\n    - UPDATE: Modify existing data (requires `ALLOW_UPDATE_OPERATION=true`)\n    - DELETE: Remove data (requires `ALLOW_DELETE_OPERATION=true`)\n  - All operations are executed within a transaction with proper commit\u002Frollback handling\n  - Supports prepared statements for secure parameter handling\n  - Configurable query timeouts and result pagination\n  - Built-in query execution statistics\n\n### Resources\n\nThe server provides comprehensive database information:\n\n- **Table Schemas**\n  - JSON schema information for each table\n  - Column names and data types\n  - Index information and constraints\n  - Foreign key relationships\n  - Table statistics and metrics\n  - Automatically discovered from database metadata\n\n### Security Features\n\n- SQL injection prevention through prepared statements\n- Query whitelisting\u002Fblacklisting capabilities\n- Rate limiting for query execution\n- Query complexity analysis\n- Configurable connection encryption\n- Read-only transaction enforcement\n\n### Performance Optimizations\n\n- Optimized connection pooling\n- Query result caching\n- Large result set streaming\n- Query execution plan analysis\n- Configurable query timeouts\n\n### Monitoring and Debugging\n\n- Comprehensive query logging\n- Performance metrics collection\n- Error tracking and reporting\n- Health check endpoints\n- Query execution statistics\n\n## Configuration\n\n### Automatic Configuration with Smithery\n\nIf you installed using Smithery, your configuration is already set up. You can view or modify it with:\n\n```bash\nsmithery configure @benborla29\u002Fmcp-server-mysql\n```\n\nWhen reconfiguring, you can update any of the MySQL connection details as well as the write operation settings:\n\n- **Basic connection settings**:\n  - MySQL Host, Port, User, Password, Database\n  - SSL\u002FTLS configuration (if your database requires secure connections)\n\n- **Write operation permissions**:\n  - Allow INSERT Operations: Set to true if you want to allow adding new data\n  - Allow UPDATE Operations: Set to true if you want to allow updating existing data\n  - Allow DELETE Operations: Set to true if you want to allow deleting data\n\nFor security reasons, all write operations are disabled by default. Only enable these settings if you specifically need Claude to modify your database data.\n\n### Advanced Configuration Options\n\nFor more control over the MCP server's behavior, you can use these advanced configuration options:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp_server_mysql\": {\n      \"command\": \"\u002Fpath\u002Fto\u002Fnpx\u002Fbinary\u002Fnpx\",\n      \"args\": [\n        \"-y\",\n        \"@benborla29\u002Fmcp-server-mysql\"\n      ],\n      \"env\": {\n        \u002F\u002F Basic connection settings\n        \"MYSQL_HOST\": \"127.0.0.1\",\n        \"MYSQL_PORT\": \"3306\",\n        \"MYSQL_USER\": \"root\",\n        \"MYSQL_PASS\": \"\",\n        \"MYSQL_DB\": \"db_name\",\n        \"PATH\": \"\u002Fpath\u002Fto\u002Fnode\u002Fbin:\u002Fusr\u002Fbin:\u002Fbin\",\n\n        \u002F\u002F Performance settings\n        \"MYSQL_POOL_SIZE\": \"10\",\n        \"MYSQL_QUERY_TIMEOUT\": \"30000\",\n        \"MYSQL_CACHE_TTL\": \"60000\",\n\n        \u002F\u002F Security settings\n        \"MYSQL_RATE_LIMIT\": \"100\",\n        \"MYSQL_MAX_QUERY_COMPLEXITY\": \"1000\",\n        \"MYSQL_SSL\": \"true\",\n\n        \u002F\u002F Monitoring settings\n        \"ENABLE_LOGGING\": \"true\",\n        \"MYSQL_LOG_LEVEL\": \"info\",\n        \"MYSQL_METRICS_ENABLED\": \"true\",\n\n        \u002F\u002F Write operation flags\n        \"ALLOW_INSERT_OPERATION\": \"false\",\n        \"ALLOW_UPDATE_OPERATION\": \"false\",\n        \"ALLOW_DELETE_OPERATION\": \"false\"\n      }\n    }\n  }\n}\n```\n\n## Environment Variables\n\n### Basic Connection\n\n- `MYSQL_SOCKET_PATH`: Unix socket path for local connections (e.g., \"\u002Ftmp\u002Fmysql.sock\")\n- `MYSQL_HOST`: MySQL server host (default: \"127.0.0.1\") - ignored if MYSQL_SOCKET_PATH is set\n- `MYSQL_PORT`: MySQL server port (default: \"3306\") - ignored if MYSQL_SOCKET_PATH is set\n- `MYSQL_USER`: MySQL username (default: \"root\")\n- `MYSQL_PASS`: MySQL password\n- `MYSQL_DB`: Target database name (leave empty for multi-DB mode)\n\n#### Alternative: Connection String\n\nFor scenarios requiring frequent credential rotation or temporary connections, you can use a MySQL connection string instead of individual environment variables:\n\n- `MYSQL_CONNECTION_STRING`: MySQL CLI-format connection string (e.g., `mysql --default-auth=mysql_native_password -A -hHOST -PPORT -uUSER -pPASS database_name`)\n\nWhen `MYSQL_CONNECTION_STRING` is provided, it takes precedence over individual connection settings. This is particularly useful for:\n\n- Rotating credentials that expire frequently\n- Temporary database connections\n- Quick testing with different database configurations\n\n**Note:** For security, this should only be set via environment variables, not stored in version-controlled configuration files. Consider using the `prompt` input type in Claude Code's MCP configuration for credentials that expire.\n\n### Performance Configuration\n\n- `MYSQL_POOL_SIZE`: Connection pool size (default: \"10\")\n- `MYSQL_QUERY_TIMEOUT`: Query timeout in milliseconds (default: \"30000\")\n- `MYSQL_CACHE_TTL`: Cache time-to-live in milliseconds (default: \"60000\")\n- `MYSQL_QUEUE_LIMIT`: Maximum number of queued connection requests (default: \"100\")\n- `MYSQL_CONNECT_TIMEOUT`: Connection timeout in milliseconds (default: \"10000\")\n\n### Security Configuration\n\n- `MYSQL_RATE_LIMIT`: Maximum queries per minute (default: \"100\")\n- `MYSQL_MAX_QUERY_COMPLEXITY`: Maximum query complexity score (default: \"1000\")\n- `MYSQL_SSL`: Enable SSL\u002FTLS encryption (default: \"false\")\n- `MYSQL_SSL_CA`: Path to SSL CA certificate file (PEM format). Only used when `MYSQL_SSL=true`. Required for connecting to MySQL instances with self-signed certificates or custom CAs.\n- `MYSQL_SSL_CERT`: Path to the client certificate file (PEM format) for mTLS. Only used when `MYSQL_SSL=true`. Enables mutual TLS (mTLS) authentication, where both the server and client present certificates. Required by some database configurations that enforce client certificate verification.\n- `MYSQL_SSL_KEY`: Path to the client private key file (PEM format) for mTLS. Only used when `MYSQL_SSL=true`. Must correspond to the certificate specified by `MYSQL_SSL_CERT`.\n- `ALLOW_INSERT_OPERATION`: Enable INSERT operations (default: \"false\")\n- `ALLOW_UPDATE_OPERATION`: Enable UPDATE operations (default: \"false\")\n- `ALLOW_DELETE_OPERATION`: Enable DELETE operations (default: \"false\")\n- `ALLOW_DDL_OPERATION`: Enable DDL operations (default: \"false\")\n- `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS`: **[NEW]** Disable read-only transaction enforcement (default: \"false\") ⚠️ **Security Warning:** Only enable this if you need full write capabilities and trust the LLM with your database\n- `SCHEMA_INSERT_PERMISSIONS`: Schema-specific INSERT permissions\n- `SCHEMA_UPDATE_PERMISSIONS`: Schema-specific UPDATE permissions\n- `SCHEMA_DELETE_PERMISSIONS`: Schema-specific DELETE permissions\n- `SCHEMA_DDL_PERMISSIONS`: Schema-specific DDL permissions\n- `MULTI_DB_WRITE_MODE`: Enable write operations in multi-DB mode (default: \"false\")\n\n### Timezone and Date Configuration\n\n- `MYSQL_TIMEZONE`: Set the timezone for date\u002Ftime values. Accepts formats like `+08:00` (UTC+8), `-05:00` (UTC-5), `Z` (UTC), or `local` (system timezone). Useful for ensuring consistent date\u002Ftime handling across different server locations.\n- `MYSQL_DATE_STRINGS`: When set to `\"true\"`, returns date\u002Fdatetime values as strings instead of JavaScript Date objects. This preserves the exact database values without any timezone conversion, which is particularly useful for:\n  - Applications that need precise control over date formatting\n  - Cross-timezone database operations\n  - Avoiding JavaScript Date timezone quirks\n\n### Monitoring Configuration\n\n- `MYSQL_ENABLE_LOGGING`: Enable query logging (default: \"false\")\n- `MYSQL_LOG_LEVEL`: Logging level (default: \"info\")\n- `MYSQL_METRICS_ENABLED`: Enable performance metrics (default: \"false\")\n\n### Remote MCP Configuration\n\n- `IS_REMOTE_MCP`: Enable remote MCP mode (default: \"false\")\n- `REMOTE_SECRET_KEY`: Secret key for remote MCP authentication (default: \"\"). If not provided, remote MCP mode will be disabled.\n- `PORT`: Port number for the remote MCP server (default: 3000)\n\n## Multi-DB Mode\n\nMCP-Server-MySQL supports connecting to multiple databases when no specific database is set. This allows the LLM to query any database the MySQL user has access to. For full details, see [README-MULTI-DB.md](.\u002FREADME-MULTI-DB.md).\n\n### Enabling Multi-DB Mode\n\nTo enable multi-DB mode, simply leave the `MYSQL_DB` environment variable empty. In multi-DB mode, queries require schema qualification:\n\n```sql\n-- Use fully qualified table names\nSELECT * FROM database_name.table_name;\n\n-- Or use USE statements to switch between databases\nUSE database_name;\nSELECT * FROM table_name;\n```\n\n## Schema-Specific Permissions\n\nFor fine-grained control over database operations, MCP-Server-MySQL now supports schema-specific permissions. This allows different databases to have different levels of access (read-only, read-write, etc.).\n\n### Configuration Example\n\n```txt\nSCHEMA_INSERT_PERMISSIONS=development:true,test:true,production:false\nSCHEMA_UPDATE_PERMISSIONS=development:true,test:true,production:false\nSCHEMA_DELETE_PERMISSIONS=development:false,test:true,production:false\nSCHEMA_DDL_PERMISSIONS=development:false,test:true,production:false\n```\n\nFor complete details and security recommendations, see [README-MULTI-DB.md](.\u002FREADME-MULTI-DB.md).\n\n## Testing\n\n### Database Setup\n\nBefore running tests, you need to set up the test database and seed it with test data:\n\n1. **Create Test Database and User**\n\n   ```sql\n   -- Connect as root and create test database\n   CREATE DATABASE IF NOT EXISTS mcp_test;\n\n   -- Create test user with appropriate permissions\n   CREATE USER IF NOT EXISTS 'mcp_test'@'localhost' IDENTIFIED BY 'mcp_test_password';\n   GRANT ALL PRIVILEGES ON mcp_test.* TO 'mcp_test'@'localhost';\n   FLUSH PRIVILEGES;\n   ```\n\n2. **Run Database Setup Script**\n\n   ```bash\n   # Run the database setup script\n   pnpm run setup:test:db\n   ```\n\n   This will create the necessary tables and seed data. The script is located in `scripts\u002Fsetup-test-db.ts`\n\n3. **Configure Test Environment**\n   Create a `.env.test` file in the project root (if not existing):\n\n   ```env\n   MYSQL_HOST=127.0.0.1\n   MYSQL_PORT=3306\n   MYSQL_USER=mcp_test\n   MYSQL_PASS=mcp_test_password\n   MYSQL_DB=mcp_test\n   ```\n\n4. **Update package.json Scripts**\n   Add these scripts to your package.json:\n\n   ```json\n   {\n     \"scripts\": {\n       \"setup:test:db\": \"ts-node scripts\u002Fsetup-test-db.ts\",\n       \"pretest\": \"pnpm run setup:test:db\",\n       \"test\": \"vitest run\",\n       \"test:watch\": \"vitest\",\n       \"test:coverage\": \"vitest run --coverage\"\n     }\n   }\n   ```\n\n### Running Tests\n\nThe project includes a comprehensive test suite to ensure functionality and reliability:\n\n```bash\n# First-time setup\npnpm run setup:test:db\n\n# Run all tests\npnpm test\n```\n\n## Running evals\n\nThe evals package loads an mcp client that then runs the index.ts file, so there is no need to rebuild between tests. You can load environment variables by prefixing the npx command. Full documentation can be found at [MCP Evals](https:\u002F\u002Fwww.mcpevals.io\u002Fdocs).\n\n```bash\nOPENAI_API_KEY=your-key  npx mcp-eval evals.ts index.ts\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Connection Issues**\n   - Verify MySQL server is running and accessible\n   - Check credentials and permissions\n   - Ensure SSL\u002FTLS configuration is correct if enabled\n   - Try connecting with a MySQL client to confirm access\n\n2. **Performance Issues**\n   - Adjust connection pool size\n   - Configure query timeout values\n   - Enable query caching if needed\n   - Check query complexity settings\n   - Monitor server resource usage\n\n3. **Security Restrictions**\n   - Review rate limiting configuration\n   - Check query whitelist\u002Fblacklist settings\n   - Verify SSL\u002FTLS settings\n   - Ensure the user has appropriate MySQL permissions\n\n4. **Path Resolution**\n   If you encounter an error \"Could not connect to MCP server mcp-server-mysql\", explicitly set the path of all required binaries:\n\n   ```json\n   {\n     \"env\": {\n       \"PATH\": \"\u002Fpath\u002Fto\u002Fnode\u002Fbin:\u002Fusr\u002Fbin:\u002Fbin\"\n     }\n   }\n   ```\n\n   *Where can I find my `node` bin path*\n   Run the following command to get it:\n\n   For **PATH**\n\n   ```bash\n   echo \"$(which node)\u002F..\u002F\"\n   ```\n\n   For **NODE_PATH**\n\n   ```bash\n   echo \"$(which node)\u002F..\u002F..\u002Flib\u002Fnode_modules\"\n   ```\n\n5. **Claude Desktop Specific Issues**\n   - If you see \"Server disconnected\" logs in Claude Desktop, check the logs at `~\u002FLibrary\u002FLogs\u002FClaude\u002Fmcp-server-mcp_server_mysql.log`\n   - Ensure you're using the absolute path to both the Node binary and the server script\n   - Check if your `.env` file is being properly loaded; use explicit environment variables in the configuration\n   - Try running the server directly from the command line to see if there are connection issues\n   - If you need write operations (INSERT, UPDATE, DELETE), set the appropriate flags to \"true\" in your configuration:\n\n     ```json\n     \"env\": {\n       \"ALLOW_INSERT_OPERATION\": \"true\",  \u002F\u002F Enable INSERT operations\n       \"ALLOW_UPDATE_OPERATION\": \"true\",  \u002F\u002F Enable UPDATE operations\n       \"ALLOW_DELETE_OPERATION\": \"true\"   \u002F\u002F Enable DELETE operations\n     }\n     ```\n\n   - Ensure your MySQL user has the appropriate permissions for the operations you're enabling\n   - For direct execution configuration, use:\n\n     ```json\n     {\n       \"mcpServers\": {\n         \"mcp_server_mysql\": {\n           \"command\": \"\u002Ffull\u002Fpath\u002Fto\u002Fnode\",\n           \"args\": [\n             \"\u002Ffull\u002Fpath\u002Fto\u002Fmcp-server-mysql\u002Fdist\u002Findex.js\"\n           ],\n           \"env\": {\n             \"MYSQL_HOST\": \"127.0.0.1\",\n             \"MYSQL_PORT\": \"3306\",\n             \"MYSQL_USER\": \"root\",\n             \"MYSQL_PASS\": \"your_password\",\n             \"MYSQL_DB\": \"your_database\"\n           }\n         }\n       }\n     }\n     ```\n\n6. **Authentication Issues**\n   - For MySQL 8.0+, ensure the server supports the `caching_sha2_password` authentication plugin\n   - Check if your MySQL user is configured with the correct authentication method\n   - Try creating a user with legacy authentication if needed:\n\n     ```sql\n     CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';\n     ```\n\n     @lizhuangs\n\n7. I am encountering `Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from` error\n   try this workaround:\n\n   ```bash\n   npx -y -p @benborla29\u002Fmcp-server-mysql -p dotenv mcp-server-mysql\n   ```\n\n   Thanks to @lizhuangs\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request to\n[https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql](https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql)\n\n## Many Thanks to the following Contributors\n\n[![Contributors](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fbenborla_mcp-server-mysql_readme_b7578952e739.png)](https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql\u002Fgraphs\u002Fcontributors)\n\n### Development Setup\n\n1. Clone the repository\n2. Install dependencies: `pnpm install`\n3. Build the project: `pnpm run build`\n4. Run tests: `pnpm test`\n\n### Project Roadmap\n\nWe're actively working on enhancing this MCP server. Check our [CHANGELOG.md](.\u002FCHANGELOG.md) for details on planned features, including:\n\n- Enhanced query capabilities with prepared statements\n- Advanced security features\n- Performance optimizations\n- Comprehensive monitoring\n- Expanded schema information\n\nIf you'd like to contribute to any of these areas, please check the issues on GitHub or open a new one to discuss your ideas.\n\n### Submitting Changes\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature\u002Fyour-feature-name`\n3. Commit your changes: `git commit -am 'Add some feature'`\n4. Push to the branch: `git push origin feature\u002Fyour-feature-name`\n5. Submit a pull request\n\n## License\n\nThis MCP server is licensed under the MIT License. See the LICENSE file for details.\n","# MySQL 的 MCP 服务器 - Claude Code 版\n\n> **🚀 这是一个针对 Claude Code 优化的修改版本，支持 SSH 隧道**  \n> **原作者:** [@benborla29](https:\u002F\u002Fgithub.com\u002Fbenborla)  \n> **原始仓库:** [https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql](https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql)  \n> **许可证:** MIT  \n\n## 基于 NodeJS 的 MySQL 的 MCP 服务器\n\n[![信任评分](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fbenborla_mcp-server-mysql_readme_5dfccc754b71.png)](https:\u002F\u002Farchestra.ai\u002Fmcp-catalog\u002Fbenborla__mcp-server-mysql)\n\n### 本分支的主要特性\n\n- ✅ **Claude Code 集成** - 针对 Anthropic 的 Claude Code CLI 进行优化\n- ✅ **SSH 隧道支持** - 内置对远程数据库的 SSH 隧道支持\n- ✅ **自动启动\u002F停止钩子** - 与 Claude 的启动\u002F停止功能无缝对接，自动管理隧道\n- ✅ **DDL 操作支持** - 添加了 `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS` 环境变量，支持 CREATE TABLE 操作\n- ✅ **多项目配置** - 轻松为多个项目配置不同的数据库\n\n### Claude Code 用户快速入门\n\n1. **阅读设置指南**: 请参阅 [PROJECT_SETUP_GUIDE.md](PROJECT_SETUP_GUIDE.md)，获取详细说明\n2. **配置 SSH 隧道**: 设置远程数据库的自动 SSH 隧道\n3. **与 Claude 配合使用**: 集成的 MCP 服务器可与 Claude Code 无缝协作\n\n这是一个通过 SSH 隧道提供 MySQL 数据库访问的 Model Context Protocol 服务器。该服务器使 Claude 及其他大语言模型能够安全地检查数据库模式并执行 SQL 查询。\n\n## 目录\n\n- [要求](#requirements)\n- [安装](#installation)\n  - [Smithery](#using-smithery)\n  - [克隆到本地仓库](#running-from-local-repository)\n  - [远程模式](#run-in-remote-mode)\n- [组件](#components)\n- [配置](#configuration)\n- [环境变量](#environment-variables)\n- [多数据库模式](#multi-db-mode)\n- [模式级权限](#schema-specific-permissions)\n- [测试](#testing)\n- [故障排除](#troubleshooting)\n- [贡献](#contributing)\n- [许可证](#license)\n\n## 要求\n\n- Node.js v20 或更高版本\n- MySQL 5.7 或更高版本（推荐使用 MySQL 8.0+）\n- 具备所需操作权限的 MySQL 用户\n- 对于写操作：具备 INSERT、UPDATE 和\u002F或 DELETE 权限的 MySQL 用户\n\n## 安装\n\n### 使用 Smithery\n\n有多种方式可以安装和配置 MCP 服务器，但最常见的方式是访问此网站 [https:\u002F\u002Fsmithery.ai\u002Fserver\u002F@benborla29\u002Fmcp-server-mysql](https:\u002F\u002Fsmithery.ai\u002Fserver\u002F@benborla29\u002Fmcp-server-mysql)\n\n### Cursor\n\n对于 Cursor IDE，您可以在项目中使用以下命令安装此 MCP 服务器：\n\n1. 访问 [https:\u002F\u002Fsmithery.ai\u002Fserver\u002F@benborla29\u002Fmcp-server-mysql](https:\u002F\u002Fsmithery.ai\u002Fserver\u002F@benborla29\u002Fmcp-server-mysql)\n2. 按照 Cursor 的指示操作\n\nMCP Get 提供了一个集中式的 MCP 服务器注册表，简化了安装流程。\n\n### Codex CLI\n\nCodex CLI 的安装方式与 Claude Code 类似：\n\n```bash\ncodex mcp add mcp_server_mysql \\\n  --env MYSQL_HOST=\"127.0.0.1\" \\\n  --env MYSQL_PORT=\"3306\" \\\n  --env MYSQL_USER=\"root\" \\\n  --env MYSQL_PASS=\"your_password\" \\\n  --env MYSQL_DB=\"your_database\" \\\n  --env ALLOW_INSERT_OPERATION=\"false\" \\\n  --env ALLOW_UPDATE_OPERATION=\"false\" \\\n  --env ALLOW_DELETE_OPERATION=\"false\" \\\n  -- npx -y @benborla29\u002Fmcp-server-mysql\n```\n\n### Claude Code\n\n#### 方法一：从 Claude Desktop 导入（已配置时推荐）\n\n如果您已经在 Claude Desktop 中配置了此 MCP 服务器，可以直接导入：\n\n```bash\nclaude mcp add-from-claude-desktop\n```\n\n这将弹出一个交互式对话框，您可以选择要导入的 `mcp_server_mysql` 服务器，并保留所有现有配置。\n\n#### 方法二：手动配置\n\n**使用 NPM\u002FPNPM 全局安装：**\n\n首先，全局安装该包：\n\n```bash\n# 使用 npm\nnpm install -g @benborla29\u002Fmcp-server-mysql\n\n# 使用 pnpm\npnpm add -g @benborla29\u002Fmcp-server-mysql\n```\n\n然后将服务器添加到 Claude Code：\n\n```bash\nclaude mcp add mcp_server_mysql \\\n  -e MYSQL_HOST=\"127.0.0.1\" \\\n  -e MYSQL_PORT=\"3306\" \\\n  -e MYSQL_USER=\"root\" \\\n  -e MYSQL_PASS=\"your_password\" \\\n  -e MYSQL_DB=\"your_database\" \\\n  -e ALLOW_INSERT_OPERATION=\"false\" \\\n  -e ALLOW_UPDATE_OPERATION=\"false\" \\\n  -e ALLOW_DELETE_OPERATION=\"false\" \\\n  -- npx @benborla29\u002Fmcp-server-mysql\n```\n\n**使用本地仓库（用于开发）：**\n\n如果您是从克隆的仓库运行：\n\n```bash\nclaude mcp add mcp_server_mysql \\\n  -e MYSQL_HOST=\"127.0.0.1\" \\\n  -e MYSQL_PORT=\"3306\" \\\n  -e MYSQL_USER=\"root\" \\\n  -e MYSQL_PASS=\"your_password\" \\\n  -e MYSQL_DB=\"your_database\" \\\n  -e ALLOW_INSERT_OPERATION=\"false\" \\\n  -e ALLOW_UPDATE_OPERATION=\"false\" \\\n  -e ALLOW_DELETE_OPERATION=\"false\" \\\n  -e PATH=\"\u002Fpath\u002Fto\u002Fnode\u002Fbin:\u002Fusr\u002Fbin:\u002Fbin\" \\\n  -e NODE_PATH=\"\u002Fpath\u002Fto\u002Fnode\u002Flib\u002Fnode_modules\" \\\n  -- \u002Fpath\u002Fto\u002Fnode \u002Ffull\u002Fpath\u002Fto\u002Fmcp-server-mysql\u002Fdist\u002Findex.js\n```\n\n请替换：\n\n- `\u002Fpath\u002Fto\u002Fnode` 为您 Node.js 可执行文件的路径（可通过 `which node` 查找）\n- `\u002Ffull\u002Fpath\u002Fto\u002Fmcp-server-mysql` 为您的克隆仓库的完整路径\n- 更新 MySQL 凭证以匹配您的环境\n\n**使用 Unix 套接字连接：**\n\n对于使用 Unix 套接字的本地 MySQL 实例：\n\n```bash\nclaude mcp add mcp_server_mysql \\\n  -e MYSQL_SOCKET_PATH=\"\u002Ftmp\u002Fmysql.sock\" \\\n  -e MYSQL_USER=\"root\" \\\n  -e MYSQL_PASS=\"your_password\" \\\n  -e MYSQL_DB=\"your_database\" \\\n  -e ALLOW_INSERT_OPERATION=\"false\" \\\n  -e ALLOW_UPDATE_OPERATION=\"false\" \\\n  -e ALLOW_DELETE_OPERATION=\"false\" \\\n  -- npx @benborla29\u002Fmcp-server-mysql\n```\n\n#### 选择合适的范围\n\n根据您的需求选择合适的范围：\n\n```bash\n# 本地范围（默认）：仅在当前项目中可用\nclaude mcp add mcp_server_mysql [选项...]\n\n# 用户范围：在所有项目中均可使用\nclaude mcp add mcp_server_mysql -s user [选项...]\n\n# 项目范围：可通过 .mcp.json 文件与团队成员共享\nclaude mcp add mcp_server_mysql -s project [选项...]\n```\n\n对于包含凭据的数据库服务器，建议使用 **本地** 或 **用户** 范围，以保护凭据的安全性。\n\n#### 验证\n\n添加服务器后，请验证其是否正确配置：\n\n```bash\n# 列出所有已配置的服务器\nclaude mcp list\n\n# 获取您的 MySQL 服务器的详细信息\nclaude mcp get mcp_server_mysql\n\n# 在 Claude Code 中检查服务器状态\n\u002Fmcp\n```\n\n#### 多数据库配置\n\n对于多数据库模式，省略 `MYSQL_DB` 环境变量：\n\n```bash\nclaude mcp add mcp_server_mysql_multi \\\n  -e MYSQL_HOST=\"127.0.0.1\" \\\n  -e MYSQL_PORT=\"3306\" \\\n  -e MYSQL_USER=\"root\" \\\n  -e MYSQL_PASS=\"your_password\" \\\n  -e MULTI_DB_WRITE_MODE=\"false\" \\\n  -- npx @benborla29\u002Fmcp-server-mysql\n```\n\n#### 高级配置\n\n如需使用高级功能，请添加以下环境变量：\n\n```bash\nclaude mcp add mcp_server_mysql \\\n  -e MYSQL_HOST=\"127.0.0.1\" \\\n  -e MYSQL_PORT=\"3306\" \\\n  -e MYSQL_USER=\"root\" \\\n  -e MYSQL_PASS=\"your_password\" \\\n  -e MYSQL_DB=\"your_database\" \\\n  -e MYSQL_POOL_SIZE=\"10\" \\\n  -e MYSQL_QUERY_TIMEOUT=\"30000\" \\\n  -e MYSQL_CACHE_TTL=\"60000\" \\\n  -e MYSQL_RATE_LIMIT=\"100\" \\\n  -e MYSQL_SSL=\"true\" \\\n  -e ALLOW_INSERT_OPERATION=\"false\" \\\n  -e ALLOW_UPDATE_OPERATION=\"false\" \\\n  -e ALLOW_DELETE_OPERATION=\"false\" \\\n  -e MYSQL_ENABLE_LOGGING=\"true\" \\\n  -- npx @benborla29\u002Fmcp-server-mysql\n```\n\n#### Claude Code 设置故障排除\n\n1. **服务器连接问题**：在 Claude Code 中使用 `\u002Fmcp` 命令检查服务器状态，并在必要时进行身份验证。\n\n2. **路径问题**：如果使用本地仓库，请确保 Node.js 路径已正确设置：\n\n   ```bash\n   # 查找 Node.js 路径\n   which node\n\n   # 对于 PATH 环境变量\n   echo \"$(which node)\u002F..\u002F\"\n\n   # 对于 NODE_PATH 环境变量\n   echo \"$(which node)\u002F..\u002F..\u002Flib\u002Fnode_modules\"\n   ```\n\n3. **权限错误**：请确保您的 MySQL 用户拥有您所启用操作的相应权限。\n\n4. **服务器未启动**：检查 Claude Code 日志或直接运行服务器以进行调试：\n\n   ```bash\n   # 直接测试服务器\n   npx @benborla29\u002Fmcp-server-mysql\n   ```\n\n### 使用 NPM\u002FPNPM\n\n手动安装方法如下：\n\n```bash\n# 使用 npm\nnpm install -g @benborla29\u002Fmcp-server-mysql\n\n# 使用 pnpm\npnpm add -g @benborla29\u002Fmcp-server-mysql\n```\n\n手动安装完成后，您需要配置您的 LLM 应用程序以使用 MCP 服务器（请参阅下方的配置部分）。\n\n### 从本地仓库运行\n\n如果您希望直接从源代码克隆并运行此 MCP 服务器，请按照以下步骤操作：\n\n1. **克隆仓库**\n\n   ```bash\n   git clone https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql.git\n   cd mcp-server-mysql\n   ```\n\n2. **安装依赖项**\n\n   ```bash\n   npm install\n   # 或\n   pnpm install\n   ```\n\n3. **构建项目**\n\n   ```bash\n   npm run build\n   # 或\n   pnpm run build\n   ```\n\n4. **配置 Claude Desktop**\n\n   将以下内容添加到您的 Claude Desktop 配置文件 (`claude_desktop_config.json`) 中：\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"mcp_server_mysql\": {\n         \"command\": \"\u002Fpath\u002Fto\u002Fnode\",\n         \"args\": [\n           \"\u002Ffull\u002Fpath\u002Fto\u002Fmcp-server-mysql\u002Fdist\u002Findex.js\"\n         ],\n         \"env\": {\n           \"MYSQL_HOST\": \"127.0.0.1\",\n           \"MYSQL_PORT\": \"3306\",\n           \"MYSQL_USER\": \"root\",\n           \"MYSQL_PASS\": \"your_password\",\n           \"MYSQL_DB\": \"your_database\",\n           \"ALLOW_INSERT_OPERATION\": \"false\",\n           \"ALLOW_UPDATE_OPERATION\": \"false\",\n           \"ALLOW_DELETE_OPERATION\": \"false\",\n           \"PATH\": \"\u002Fpath\u002Fto\u002Fnode\u002Fbin:\u002Fusr\u002Fbin:\u002Fbin\", \u002F\u002F \u003C--- 重要：请运行 `echo \"$(which node)\u002F..\u002F\"` 来获取路径\n           \"NODE_PATH\": \"\u002Fpath\u002Fto\u002Fnode\u002Flib\u002Fnode_modules\" \u002F\u002F \u003C--- 重要：请运行 `echo \"$(which node)\u002F..\u002F..\u002Flib\u002Fnode_modules\"` 来获取路径\n         }\n       }\n     }\n   }\n   ```\n\n   替换：\n   - `\u002Fpath\u002Fto\u002Fnode` 为您的 Node.js 可执行文件的完整路径（可通过 `which node` 查找）\n   - `\u002Ffull\u002Fpath\u002Fto\u002Fmcp-server-mysql` 为您克隆仓库的完整路径\n   - 根据您的环境设置 MySQL 凭证\n\n5. **测试服务器**\n\n   ```bash\n   # 直接运行服务器进行测试\n   node dist\u002Findex.js\n   ```\n\n   如果成功连接到 MySQL，则可以将其与 Claude Desktop 一起使用。\n\n### 远程模式运行\n\n要在远程模式下运行，您需要向 npx 脚本提供 [环境变量](https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql?tab=readme-ov-file#environment-variables)。\n\n1. 在首选目录中创建 `.env` 文件：\n\n   ```bash\n   # 创建 .env 文件\n   touch .env\n   ```\n\n2. 复制并粘贴此仓库中的 [示例文件](https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql\u002Fblob\u002Fmain\u002F.env)\n3. 根据您的环境设置 MySQL 凭证\n4. 设置 `IS_REMOTE_MCP=true`\n5. 设置一个安全的字符串作为 `REMOTE_SECRET_KEY`\n6. 如有需要，可自定义 `PORT`。默认值为 3000。\n7. 在当前会话中加载变量：\n\n   ```bash\n   source .env\n   ```\n\n8. 运行服务器：\n\n   ```bash\n   npx @benborla29\u002Fmcp-server-mysql\n   ```\n\n9. 配置您的代理以通过以下配置连接到 MCP：\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"mysql\": {\n         \"url\": \"http:\u002F\u002Fyour-host:3000\u002Fmcp\",\n         \"type\": \"streamableHttp\",\n         \"headers\": {\n           \"Authorization\": \"Bearer \u003CREMOTE_SECRET_KEY>\"\n         }\n       }\n     }\n   }\n   ```\n\n## 组件\n\n### 工具\n\n- **mysql_query**\n  - 对连接的数据库执行 SQL 查询\n  - 输入：`sql`（字符串）：要执行的 SQL 查询\n  - 默认情况下，仅限只读操作\n  - 可选写入操作（通过配置启用）：\n    - INSERT：向表中添加新数据（需设置 `ALLOW_INSERT_OPERATION=true`）\n    - UPDATE：修改现有数据（需设置 `ALLOW_UPDATE_OPERATION=true`）\n    - DELETE：删除数据（需设置 `ALLOW_DELETE_OPERATION=true`）\n  - 所有操作均在事务中执行，并妥善处理提交和回滚\n  - 支持预处理语句以安全地处理参数\n  - 可配置查询超时时间和结果分页\n  - 内置查询执行统计信息\n\n### 资源\n\n服务器提供全面的数据库信息：\n\n- **表结构**\n  - 每个表的 JSON 模式信息\n  - 列名和数据类型\n  - 索引信息和约束条件\n  - 外键关系\n  - 表统计信息和指标\n  - 自动从数据库元数据中发现\n\n### 安全特性\n\n- 通过预处理语句防止 SQL 注入\n- 查询白名单\u002F黑名单功能\n- 查询执行速率限制\n- 查询复杂度分析\n- 可配置的连接加密\n- 强制执行只读事务\n\n### 性能优化\n\n- 优化的连接池\n- 查询结果缓存\n- 大型结果集流式传输\n- 查询执行计划分析\n- 可配置的查询超时时间\n\n### 监控与调试\n\n- 全面的查询日志记录\n- 性能指标收集\n- 错误跟踪与报告\n- 健康检查端点\n- 查询执行统计信息\n\n## 配置\n\n### 使用 Smithery 自动配置\n\n如果您使用 Smithery 进行安装，您的配置已经设置完毕。您可以通过以下命令查看或修改配置：\n\n```bash\nsmithery configure @benborla29\u002Fmcp-server-mysql\n```\n\n在重新配置时，您可以更新 MySQL 的连接信息以及写操作的相关设置：\n\n- **基本连接设置**：\n  - MySQL 主机、端口、用户名、密码、数据库\n  - SSL\u002FTLS 配置（如果您的数据库需要安全连接）\n\n- **写操作权限**：\n  - 允许 INSERT 操作：如果您希望允许添加新数据，请将其设置为 `true`\n  - 允许 UPDATE 操作：如果您希望允许更新现有数据，请将其设置为 `true`\n  - 允许 DELETE 操作：如果您希望允许删除数据，请将其设置为 `true`\n\n出于安全考虑，默认情况下所有写操作均被禁用。请仅在您明确需要 Claude 修改数据库数据时才启用这些设置。\n\n### 高级配置选项\n\n为了更精细地控制 MCP 服务器的行为，您可以使用以下高级配置选项：\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp_server_mysql\": {\n      \"command\": \"\u002Fpath\u002Fto\u002Fnpx\u002Fbinary\u002Fnpx\",\n      \"args\": [\n        \"-y\",\n        \"@benborla29\u002Fmcp-server-mysql\"\n      ],\n      \"env\": {\n        \u002F\u002F 基本连接设置\n        \"MYSQL_HOST\": \"127.0.0.1\",\n        \"MYSQL_PORT\": \"3306\",\n        \"MYSQL_USER\": \"root\",\n        \"MYSQL_PASS\": \"\",\n        \"MYSQL_DB\": \"db_name\",\n        \"PATH\": \"\u002Fpath\u002Fto\u002Fnode\u002Fbin:\u002Fusr\u002Fbin:\u002Fbin\",\n\n        \u002F\u002F 性能设置\n        \"MYSQL_POOL_SIZE\": \"10\",\n        \"MYSQL_QUERY_TIMEOUT\": \"30000\",\n        \"MYSQL_CACHE_TTL\": \"60000\",\n\n        \u002F\u002F 安全设置\n        \"MYSQL_RATE_LIMIT\": \"100\",\n        \"MYSQL_MAX_QUERY_COMPLEXITY\": \"1000\",\n        \"MYSQL_SSL\": \"true\",\n\n        \u002F\u002F 监控设置\n        \"ENABLE_LOGGING\": \"true\",\n        \"MYSQL_LOG_LEVEL\": \"info\",\n        \"MYSQL_METRICS_ENABLED\": \"true\",\n\n        \u002F\u002F 写操作标志\n        \"ALLOW_INSERT_OPERATION\": \"false\",\n        \"ALLOW_UPDATE_OPERATION\": \"false\",\n        \"ALLOW_DELETE_OPERATION\": \"false\"\n      }\n    }\n  }\n}\n```\n\n## 环境变量\n\n### 基本连接\n\n- `MYSQL_SOCKET_PATH`：用于本地连接的 Unix 套接字路径（例如 `\"\u002Ftmp\u002Fmysql.sock\"`）\n- `MYSQL_HOST`：MySQL 服务器主机（默认值为 `127.0.0.1`），若设置了 `MYSQL_SOCKET_PATH` 则忽略此设置\n- `MYSQL_PORT`：MySQL 服务器端口（默认值为 `3306`），若设置了 `MYSQL_SOCKET_PATH` 则忽略此设置\n- `MYSQL_USER`：MySQL 用户名（默认值为 `root`）\n- `MYSQL_PASS`：MySQL 密码\n- `MYSQL_DB`：目标数据库名称（留空则进入多数据库模式）\n\n#### 替代方案：连接字符串\n\n对于需要频繁轮换凭据或临时连接的场景，您可以使用 MySQL 连接字符串代替单独的环境变量：\n\n- `MYSQL_CONNECTION_STRING`：MySQL CLI 格式的连接字符串（例如 `mysql --default-auth=mysql_native_password -A -hHOST -PPORT -uUSER -pPASS database_name`）\n\n当提供了 `MYSQL_CONNECTION_STRING` 时，它将优先于单独的连接设置。这在以下情况下尤为有用：\n\n- 凭据经常过期且需要轮换\n- 临时数据库连接\n- 快速测试不同的数据库配置\n\n**注意**：出于安全考虑，此设置应仅通过环境变量进行配置，而不应存储在版本控制的配置文件中。对于会过期的凭据，建议在 Claude Code 的 MCP 配置中使用 `prompt` 输入类型。\n\n### 性能配置\n\n- `MYSQL_POOL_SIZE`：连接池大小（默认值为 `10`）\n- `MYSQL_QUERY_TIMEOUT`：查询超时时间，单位为毫秒（默认值为 `30000`）\n- `MYSQL_CACHE_TTL`：缓存存活时间，单位为毫秒（默认值为 `60000`）\n- `MYSQL_QUEUE_LIMIT`：排队等待的连接请求数量上限（默认值为 `100`）\n- `MYSQL_CONNECT_TIMEOUT`：连接超时时间，单位为毫秒（默认值为 `10000`）\n\n### 安全配置\n\n- `MYSQL_RATE_LIMIT`：每分钟最大查询次数（默认值为 `100`）\n- `MYSQL_MAX_QUERY_COMPLEXITY`：最大查询复杂度分数（默认值为 `1000`）\n- `MYSQL_SSL`：启用 SSL\u002FTLS 加密（默认值为 `false`）\n- `MYSQL_SSL_CA`：SSL CA 证书文件路径（PEM 格式）。仅在 `MYSQL_SSL=true` 时使用。连接自签名证书或使用自定义 CA 的 MySQL 实例时必须提供。\n- `MYSQL_SSL_CERT`：客户端证书文件路径（PEM 格式），用于 mTLS。仅在 `MYSQL_SSL=true` 时使用。启用双向 TLS（mTLS）认证，即服务器和客户端均需出示证书。某些强制验证客户端证书的数据库配置需要此设置。\n- `MYSQL_SSL_KEY`：客户端私钥文件路径（PEM 格式），用于 mTLS。仅在 `MYSQL_SSL=true` 时使用。必须与 `MYSQL_SSL_CERT` 中指定的证书相对应。\n- `ALLOW_INSERT_OPERATION`：启用 INSERT 操作（默认值为 `false`）\n- `ALLOW_UPDATE_OPERATION`：启用 UPDATE 操作（默认值为 `false`）\n- `ALLOW_DELETE_OPERATION`：启用 DELETE 操作（默认值为 `false`）\n- `ALLOW_DDL_OPERATION`：启用 DDL 操作（默认值为 `false`）\n- `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS`：**[新增]** 禁用只读事务强制执行（默认值为 `false`）⚠️ **安全警告**：仅在您需要完全的写入能力并信任 LLM 可以访问您的数据库时才启用此设置\n- `SCHEMA_INSERT_PERMISSIONS`：针对特定模式的 INSERT 权限\n- `SCHEMA_UPDATE_PERMISSIONS`：针对特定模式的 UPDATE 权限\n- `SCHEMA_DELETE_PERMISSIONS`：针对特定模式的 DELETE 权限\n- `SCHEMA_DDL_PERMISSIONS`：针对特定模式的 DDL 权限\n- `MULTI_DB_WRITE_MODE`：启用多数据库模式下的写操作（默认值为 `false`）\n\n### 时区和日期配置\n\n- `MYSQL_TIMEZONE`：设置日期\u002F时间值的时区。支持的格式包括 `+08:00`（UTC+8）、`-05:00`（UTC-5）、`Z`（UTC）或 `local`（系统时区）。有助于确保在不同服务器位置之间保持一致的日期\u002F时间处理。\n- `MYSQL_DATE_STRINGS`：当设置为 `\"true\"`时，日期\u002F时间值将以字符串形式返回，而不是 JavaScript Date 对象。这样可以保留数据库中的精确值，而不会进行任何时区转换，特别适用于：\n  - 需要精确控制日期格式的应用程序\n  - 跨时区的数据库操作\n  - 避免 JavaScript Date 的时区问题\n\n### 监控配置\n\n- `MYSQL_ENABLE_LOGGING`：启用查询日志记录（默认值为 `false`）\n- `MYSQL_LOG_LEVEL`：日志级别（默认值为 `info`）\n- `MYSQL_METRICS_ENABLED`：启用性能指标（默认值为 `false`）\n\n### 远程 MCP 配置\n\n- `IS_REMOTE_MCP`：启用远程 MCP 模式（默认值为 `false`）\n- `REMOTE_SECRET_KEY`：用于远程 MCP 认证的密钥（默认值为空）。若未提供，则远程 MCP 模式将被禁用。\n- `PORT`：远程 MCP 服务器的端口号（默认值为 3000）\n\n## 多数据库模式\n\nMCP-Server-MySQL 支持在未指定具体数据库的情况下连接多个数据库。这使得 LLM 可以查询 MySQL 用户有权访问的任意数据库。有关详细信息，请参阅 [README-MULTI-DB.md](.\u002FREADME-MULTI-DB.md)。\n\n### 启用多数据库模式\n\n要启用多数据库模式，只需将 `MYSQL_DB` 环境变量留空。在多数据库模式下，查询需要指定模式：\n\n```sql\n-- 使用完全限定的表名\nSELECT * FROM 数据库名.表名;\n\n-- 或者使用 USE 语句切换数据库\nUSE 数据库名;\nSELECT * FROM 表名;\n```\n\n## 模式特定的权限\n\n为了对数据库操作进行细粒度控制，MCP-Server-MySQL 现在支持模式特定的权限。这允许不同的数据库拥有不同的访问级别（只读、读写等）。\n\n### 配置示例\n\n```txt\nSCHEMA_INSERT_PERMISSIONS=development:true,test:true,production:false\nSCHEMA_UPDATE_PERMISSIONS=development:true,test:true,production:false\nSCHEMA_DELETE_PERMISSIONS=development:false,test:true,production:false\nSCHEMA_DDL_PERMISSIONS=development:false,test:true,production:false\n```\n\n有关完整详情和安全建议，请参阅 [README-MULTI-DB.md](.\u002FREADME-MULTI-DB.md)。\n\n## 测试\n\n### 数据库设置\n\n在运行测试之前，您需要设置测试数据库并填充测试数据：\n\n1. **创建测试数据库和用户**\n\n   ```sql\n   -- 以 root 用户身份连接并创建测试数据库\n   CREATE DATABASE IF NOT EXISTS mcp_test;\n\n   -- 创建具有适当权限的测试用户\n   CREATE USER IF NOT EXISTS 'mcp_test'@'localhost' IDENTIFIED BY 'mcp_test_password';\n   GRANT ALL PRIVILEGES ON mcp_test.* TO 'mcp_test'@'localhost';\n   FLUSH PRIVILEGES;\n   ```\n\n2. **运行数据库设置脚本**\n\n   ```bash\n   # 运行数据库设置脚本\n   pnpm run setup:test:db\n   ```\n\n   这将创建必要的表并填充数据。该脚本位于 `scripts\u002Fsetup-test-db.ts` 中。\n\n3. **配置测试环境**\n   在项目根目录中创建 `.env.test` 文件（如果尚未存在）：\n\n   ```env\n   MYSQL_HOST=127.0.0.1\n   MYSQL_PORT=3306\n   MYSQL_USER=mcp_test\n   MYSQL_PASS=mcp_test_password\n   MYSQL_DB=mcp_test\n   ```\n\n4. **更新 package.json 脚本**\n   将以下脚本添加到您的 `package.json` 中：\n\n   ```json\n   {\n     \"scripts\": {\n       \"setup:test:db\": \"ts-node scripts\u002Fsetup-test-db.ts\",\n       \"pretest\": \"pnpm run setup:test:db\",\n       \"test\": \"vitest run\",\n       \"test:watch\": \"vitest\",\n       \"test:coverage\": \"vitest run --coverage\"\n     }\n   }\n   ```\n\n### 运行测试\n\n该项目包含一个全面的测试套件，以确保功能性和可靠性：\n\n```bash\n# 首次设置\npnpm run setup:test:db\n\n# 运行所有测试\npnpm test\n```\n\n## 运行 evals\n\nevals 包加载了一个 mcp 客户端，然后运行 `index.ts` 文件，因此无需在每次测试之间重新构建。您可以通过在 `npx` 命令前添加环境变量来加载它们。完整的文档可在 [MCP Evals](https:\u002F\u002Fwww.mcpevals.io\u002Fdocs) 上找到。\n\n```bash\nOPENAI_API_KEY=your-key  npx mcp-eval evals.ts index.ts\n```\n\n## 故障排除\n\n### 常见问题\n\n1. **连接问题**\n   - 确认 MySQL 服务器正在运行且可访问。\n   - 检查凭据和权限。\n   - 如果启用了 SSL\u002FTLS，请确保配置正确。\n   - 尝试使用 MySQL 客户端连接以确认访问权限。\n\n2. **性能问题**\n   - 调整连接池大小。\n   - 配置查询超时值。\n   - 如有必要，启用查询缓存。\n   - 检查查询复杂度设置。\n   - 监控服务器资源使用情况。\n\n3. **安全限制**\n   - 检查速率限制配置。\n   - 查看查询白名单\u002F黑名单设置。\n   - 验证 SSL\u002FTLS 设置。\n   - 确保用户具有适当的 MySQL 权限。\n\n4. **路径解析问题**\n   如果遇到“无法连接到 MCP 服务器 mcp-server-mysql”的错误，请显式设置所有所需二进制文件的路径：\n\n   ```json\n   {\n     \"env\": {\n       \"PATH\": \"\u002Fpath\u002Fto\u002Fnode\u002Fbin:\u002Fusr\u002Fbin:\u002Fbin\"\n     }\n   }\n   ```\n\n   *如何找到我的 `node` 二进制文件路径？*\n   运行以下命令获取：\n\n   对于 **PATH**：\n\n   ```bash\n   echo \"$(which node)\u002F..\u002F\"\n   ```\n\n   对于 **NODE_PATH**：\n\n   ```bash\n   echo \"$(which node)\u002F..\u002F..\u002Flib\u002Fnode_modules\"\n   ```\n\n5. **Claude Desktop 特定问题**\n   - 如果在 Claude Desktop 中看到“服务器断开连接”的日志，请检查 `~\u002FLibrary\u002FLogs\u002FClaude\u002Fmcp-server-mcp_server_mysql.log` 中的日志。\n   - 确保您使用的是 Node 二进制文件和服务器脚本的绝对路径。\n   - 检查 `.env` 文件是否被正确加载；在配置中使用显式环境变量。\n   - 尝试直接从命令行运行服务器，以查看是否存在连接问题。\n   - 如果需要写操作（INSERT、UPDATE、DELETE），请在配置中将相应标志设置为“true”：\n\n     ```json\n     \"env\": {\n       \"ALLOW_INSERT_OPERATION\": \"true\",  \u002F\u002F 启用 INSERT 操作\n       \"ALLOW_UPDATE_OPERATION\": \"true\",  \u002F\u002F 启用 UPDATE 操作\n       \"ALLOW_DELETE_OPERATION\": \"true\"   \u002F\u002F 启用 DELETE 操作\n     }\n     ```\n\n   - 确保您的 MySQL 用户具有您所启用操作的适当权限。\n   - 对于直接执行的配置，使用：\n\n     ```json\n     {\n       \"mcpServers\": {\n         \"mcp_server_mysql\": {\n           \"command\": \"\u002Ffull\u002Fpath\u002Fto\u002Fnode\",\n           \"args\": [\n             \"\u002Ffull\u002Fpath\u002Fto\u002Fmcp-server-mysql\u002Fdist\u002Findex.js\"\n           ],\n           \"env\": {\n             \"MYSQL_HOST\": \"127.0.0.1\",\n             \"MYSQL_PORT\": \"3306\",\n             \"MYSQL_USER\": \"root\",\n             \"MYSQL_PASS\": \"your_password\",\n             \"MYSQL_DB\": \"your_database\"\n           }\n         }\n       }\n     }\n     ```\n\n6. **认证问题**\n   - 对于 MySQL 8.0+，请确保服务器支持 `caching_sha2_password` 认证插件。\n   - 检查您的 MySQL 用户是否配置了正确的认证方法。\n   - 如有必要，尝试创建使用旧版认证的用户：\n\n     ```sql\n     CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';\n     ```\n\n     @lizhuangs\n\n7. 我遇到了 `Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from` 错误，\n   可以尝试以下解决方法：\n\n   ```bash\n   npx -y -p @benborla29\u002Fmcp-server-mysql -p dotenv mcp-server-mysql\n   ```\n\n   感谢 @lizhuangs。\n\n## 贡献\n\n欢迎贡献！请随时提交 Pull Request 到\n[https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql](https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql)\n\n## 非常感谢以下贡献者\n\n[![Contributors](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fbenborla_mcp-server-mysql_readme_b7578952e739.png)](https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql\u002Fgraphs\u002Fcontributors)\n\n### 开发设置\n\n1. 克隆仓库。\n2. 安装依赖：`pnpm install`。\n3. 构建项目：`pnpm run build`。\n4. 运行测试：`pnpm test`。\n\n### 项目路线图\n\n我们正在积极开发并优化这款 MCP 服务器。请查看我们的 [CHANGELOG.md](.\u002FCHANGELOG.md)，了解计划中的功能详情，包括：\n\n- 使用预处理语句增强查询能力\n- 高级安全特性\n- 性能优化\n- 全面的监控功能\n- 扩展的模式信息\n\n如果您希望在这些方面做出贡献，请查看 GitHub 上的相关议题，或新建一个议题来讨论您的想法。\n\n### 提交更改\n\n1. 分支仓库\n2. 创建功能分支：`git checkout -b feature\u002Fyour-feature-name`\n3. 提交更改：`git commit -am '添加某项功能'`\n4. 推送至分支：`git push origin feature\u002Fyour-feature-name`\n5. 提交拉取请求\n\n## 许可证\n\n本 MCP 服务器采用 MIT 许可证授权。详细信息请参阅 LICENSE 文件。","# mcp-server-mysql 快速上手指南\n\n本指南介绍如何为 Claude Code 配置优化版的 MySQL MCP Server，支持 SSH 隧道连接远程数据库及安全的 SQL 查询执行。\n\n## 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **Node.js**: v20 或更高版本\n*   **MySQL**: 5.7 或更高版本（推荐 8.0+）\n*   **数据库权限**:\n    *   基础读取：需具备 `SELECT` 权限\n    *   写入操作：需额外具备 `INSERT`, `UPDATE`, `DELETE` 权限（需在配置中显式开启）\n\n## 安装步骤\n\n### 方式一：通过 Claude Code CLI 直接安装（推荐）\n\n这是最快捷的方式，适用于全局使用。\n\n1.  **全局安装包**（可选，CLI 通常会自动处理，但预先安装更稳定）：\n    ```bash\n    npm install -g @benborla29\u002Fmcp-server-mysql\n    # 或者使用 pnpm\n    pnpm add -g @benborla29\u002Fmcp-server-mysql\n    ```\n\n2.  **添加服务器到 Claude Code**：\n    运行以下命令，将 MySQL 连接信息注册到 Claude Code。请替换 `\u003Cyour_...>` 占位符为您的实际数据库信息。\n\n    ```bash\n    claude mcp add mcp_server_mysql \\\n      -e MYSQL_HOST=\"127.0.0.1\" \\\n      -e MYSQL_PORT=\"3306\" \\\n      -e MYSQL_USER=\"root\" \\\n      -e MYSQL_PASS=\"your_password\" \\\n      -e MYSQL_DB=\"your_database\" \\\n      -e ALLOW_INSERT_OPERATION=\"false\" \\\n      -e ALLOW_UPDATE_OPERATION=\"false\" \\\n      -e ALLOW_DELETE_OPERATION=\"false\" \\\n      -- npx @benborla29\u002Fmcp-server-mysql\n    ```\n\n    > **安全提示**：默认情况下写操作（INSERT\u002FUPDATE\u002FDELETE）是禁用的。如需开启，请将对应环境变量设为 `\"true\"`。建议生产环境仅开启读权限。\n\n3.  **选择作用域**（可选）：\n    *   **本地项目专用**（默认，推荐用于保护凭证）：无需额外参数。\n    *   **用户全局可用**：添加 `-s user` 参数。\n    *   **团队项目共享**：添加 `-s project` 参数（凭证会写入 `.mcp.json`，请注意保密）。\n\n### 方式二：本地源码运行（开发调试用）\n\n如果您需要修改源码或使用本地克隆版本：\n\n1.  **克隆并构建项目**：\n    ```bash\n    git clone https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql.git\n    cd mcp-server-mysql\n    npm install\n    npm run build\n    ```\n\n2.  **获取 Node 路径**：\n    在终端执行以下命令获取路径，后续配置需要用到：\n    ```bash\n    which node\n    echo \"$(which node)\u002F..\u002F\"\n    echo \"$(which node)\u002F..\u002F..\u002Flib\u002Fnode_modules\"\n    ```\n\n3.  **配置 Claude Desktop\u002FCode**：\n    编辑配置文件，填入绝对路径和环境变量：\n    ```json\n    {\n      \"mcpServers\": {\n        \"mcp_server_mysql\": {\n          \"command\": \"\u002Fpath\u002Fto\u002Fnode\",\n          \"args\": [\n            \"\u002Ffull\u002Fpath\u002Fto\u002Fmcp-server-mysql\u002Fdist\u002Findex.js\"\n          ],\n          \"env\": {\n            \"MYSQL_HOST\": \"127.0.0.1\",\n            \"MYSQL_PORT\": \"3306\",\n            \"MYSQL_USER\": \"root\",\n            \"MYSQL_PASS\": \"your_password\",\n            \"MYSQL_DB\": \"your_database\",\n            \"ALLOW_INSERT_OPERATION\": \"false\",\n            \"ALLOW_UPDATE_OPERATION\": \"false\",\n            \"ALLOW_DELETE_OPERATION\": \"false\",\n            \"PATH\": \"\u002Fpath\u002Fto\u002Fnode\u002Fbin:\u002Fusr\u002Fbin:\u002Fbin\",\n            \"NODE_PATH\": \"\u002Fpath\u002Fto\u002Fnode\u002Flib\u002Fnode_modules\"\n          }\n        }\n      }\n    }\n    ```\n\n### 特殊场景配置\n\n*   **SSH 隧道连接**：此版本内置支持 SSH 隧道。若需连接远程内网数据库，请在上述环境变量中增加 SSH 相关配置（参考项目详细文档 `PROJECT_SETUP_GUIDE.md`），工具会自动管理隧道的启动与停止。\n*   **Unix Socket 连接**：如果是本地 MySQL 且使用 Socket 文件：\n    ```bash\n    claude mcp add mcp_server_mysql \\\n      -e MYSQL_SOCKET_PATH=\"\u002Ftmp\u002Fmysql.sock\" \\\n      -e MYSQL_USER=\"root\" \\\n      -e MYSQL_PASS=\"your_password\" \\\n      -e MYSQL_DB=\"your_database\" \\\n      -- npx @benborla29\u002Fmcp-server-mysql\n    ```\n*   **多数据库模式**：如果不指定 `MYSQL_DB`，可进入多库模式，允许在对话中切换数据库：\n    ```bash\n    claude mcp add mcp_server_mysql_multi \\\n      -e MYSQL_HOST=\"127.0.0.1\" \\\n      -e MYSQL_USER=\"root\" \\\n      -e MYSQL_PASS=\"your_password\" \\\n      -e MULTI_DB_WRITE_MODE=\"false\" \\\n      -- npx @benborla29\u002Fmcp-server-mysql\n    ```\n\n## 基本使用\n\n配置完成后，重启 Claude Code 或在对话中输入 `\u002Fmcp` 检查服务器状态。\n\n### 1. 验证连接\n在 Claude Code 对话框中输入：\n> \"检查 MySQL 连接状态，列出当前数据库的所有表。\"\n\n如果配置正确，Claude 将调用 `mysql_query` 工具返回表结构信息。\n\n### 2. 执行查询（只读）\n默认模式下仅允许读取操作：\n> \"查询 users 表中最近注册的 5 个用户。\"\n\n### 3. 执行写入操作（需配置开启）\n如果您在安装时设置了 `ALLOW_INSERT_OPERATION=\"true\"` 等参数：\n> \"向 logs 表中插入一条新的测试记录。\"\n\n### 4. 查看架构\n> \"分析 orders 表的 schema 结构，并解释每个字段的含义。\"\n\n该工具会自动处理事务提交\u002F回滚，并支持预处理语句以确保安全性。","某电商公司的后端工程师需要在不中断线上服务的前提下，快速排查生产环境 MySQL 数据库中订单表的异常数据并验证修复方案。\n\n### 没有 mcp-server-mysql 时\n- **上下文割裂严重**：工程师必须在 IDE 编写代码、切换终端登录 SSH 跳板机、再打开数据库客户端查看表结构，频繁切换窗口导致思路中断。\n- **手动操作风险高**：为了安全，需人工复制表结构到对话框询问 AI，容易因复制遗漏字段或拼写错误导致生成的 SQL 不可用。\n- **远程连接繁琐**：每次查询生产库都要手动建立 SSH 隧道，过程耗时且容易因配置错误连接失败，无法实现“即问即查”。\n- **反馈循环漫长**：AI 给出的查询建议无法直接验证，工程师需手动执行并截图反馈，多轮对话效率极低。\n\n### 使用 mcp-server-mysql 后\n- **工作流无缝集成**：在 Claude Code 中直接对话，mcp-server-mysql 自动通过内置 SSH 隧道连接远程库，无需离开编辑器即可读取实时表结构。\n- **精准生成可执行 SQL**：LLM 直接 inspect 数据库元数据，生成的查询语句字段准确无误，支持只读预览甚至受控的 DDL 操作（如创建临时测试表）。\n- **自动化安全管理**：工具自动处理 SSH 隧道的启动与关闭，既保证了生产库的安全访问，又免去了手动配置端口的麻烦。\n- **即时验证闭环**：工程师让 AI 直接执行查询并返回结果摘要，几秒钟内即可完成从“发现问题”到“验证假设”的全过程。\n\nmcp-server-mysql 通过将数据库上下文直接注入大模型，把原本碎片化、高风险的人工排查流程转变为流畅、安全的自动化对话式开发体验。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fbenborla_mcp-server-mysql_d7d935f2.png","benborla","Ben Borla","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fbenborla_a873e2ae.jpg","Full Stack Developer with over 9 years of experience.\r\n\r\nNow also exploring System Development using Rust",null,"Philippines","benborla@icloud.com","https:\u002F\u002Fbenborla.dev\u002F","https:\u002F\u002Fgithub.com\u002Fbenborla",[86,90,94,98],{"name":87,"color":88,"percentage":89},"JavaScript","#f1e05a",99.8,{"name":91,"color":92,"percentage":93},"TypeScript","#3178c6",0.2,{"name":95,"color":96,"percentage":97},"Shell","#89e051",0,{"name":99,"color":100,"percentage":97},"Dockerfile","#384d54",1545,195,"2026-04-16T14:04:51","MIT","未说明","不需要 GPU",{"notes":108,"python":109,"dependencies":110},"该工具基于 Node.js 开发，非 Python 项目。运行需安装 Node.js v20 或更高版本以及 MySQL 数据库（5.7+）。支持通过 SSH 隧道连接远程数据库。写操作（INSERT\u002FUPDATE\u002FDELETE）需在环境变量中显式开启。可通过 npx 直接运行或全局安装 npm 包。","不需要 Python",[111,112],"Node.js v20+","MySQL 5.7+ (推荐 8.0+)",[27,16],"2026-03-27T02:49:30.150509","2026-04-17T10:19:23.768716",[117,122,127,132,136,140],{"id":118,"question_zh":119,"answer_zh":120,"source_url":121},37397,"在 VSCode Cline 或 Cursor 中连接 MCP Server 时报错 \"Invalid URL\" 或 \"Connection closed\" 怎么办？","这通常是由于配置方式不当引起的。建议不要手动编写复杂的 npx 命令，而是直接使用官方推荐的 Smithery 安装指南进行配置。\n请访问 https:\u002F\u002Fsmithery.ai\u002Fserver\u002F@benborla29\u002Fmcp-server-mysql，选择你的编辑器（如 `Cline` 或 `Cursor`），复制生成的配置代码填入 settings.json。如果问题依旧，请检查是否使用了过时的 Node.js 版本或存在环境变量冲突。","https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql\u002Fissues\u002F15",{"id":123,"question_zh":124,"answer_zh":125,"source_url":126},37398,"Windows 用户如何正确安装和运行此 MCP Server 以避免兼容性问题？","Windows 平台用户需注意以下几点以确保正常运行：\n1. 建议通过 MSI 安装包安装 Node.js，避免使用 nvm 等版本管理工具可能引发的路径问题。\n2. 在安装新版 Node.js 前，务必完全卸载旧版本，并检查安全目录中是否有残留文件，如有需手动删除。\n3. 如果直接使用 npx 运行失败，可以尝试下载源码本地运行，配置如下：\n   - command: \"C:\\\\Program Files\\\\nodejs\\\\node.exe\"\n   - args: [\"路径\\\\到\\\\mcp-server-mysql\\\\dist\\\\index.js\"]\n   - env: 设置 MYSQL_HOST, MYSQL_PORT 等环境变量。","https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql\u002Fissues\u002F23",{"id":128,"question_zh":129,"answer_zh":130,"source_url":131},37399,"Cursor 编辑器启动时报错 \"Failed to reload client: MCP error -32000\" 且日志显示 \"Unexpected token 'R'\" 是什么原因？","该错误通常是因为启动命令输出了一些非 JSON 格式的日志信息（如 \"Reusing existing...\"），导致 MCP 客户端解析失败。\n解决方案：\n1. 检查 mcp.json 配置，确保没有多余的输出干扰。\n2. 推荐使用 Smithery 提供的标准化配置生成器来获取正确的启动参数：https:\u002F\u002Fsmithery.ai\u002Fserver\u002F@benborla29\u002Fmcp-server-mysql。\n3. 确保使用的 Cursor 版本与 MCP 协议兼容，部分旧版本（如 0.48.8）可能存在已知问题，尝试升级到最新版。","https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql\u002Fissues\u002F28",{"id":133,"question_zh":134,"answer_zh":135,"source_url":131},37400,"使用 npx mcprunner 启动时提示缺少 \"mysqlHost\" 属性错误如何解决？","这是因为通过 Smithery CLI 或某些包装器启动时，环境变量未正确传递或被识别。\n解决方法：\n1. 不要直接在 args 中拼接环境变量给 mcprunner，而是应该按照 Smithery 的指引使用 `--key` 和 `--profile` 参数，或者直接在配置文件中通过 `env` 字段传递变量。\n2. 参考官方文档重新生成配置：https:\u002F\u002Fsmithery.ai\u002Fserver\u002F@benborla29\u002Fmcp-server-mysql，确保所有必填项（如 mysqlHost, mysqlPort, mysqlUser 等）都已正确定义。",{"id":137,"question_zh":138,"answer_zh":139,"source_url":126},37401,"如何在保证安全的前提下限制数据库的写操作（INSERT\u002FUPDATE\u002FDELETE）？","可以在启动配置的环境变量中显式禁止写操作。在 mcp.json 的 args 或 env 中添加以下参数：\n- ALLOW_INSERT_OPERATION=false\n- ALLOW_UPDATE_OPERATION=false\n- ALLOW_DELETE_OPERATION=false\n例如：\n\"args\": [\n  \"mcprunner\",\n  \"MYSQL_HOST=127.0.0.1\",\n  ...\n  \"ALLOW_INSERT_OPERATION=false\",\n  \"ALLOW_UPDATE_OPERATION=false\",\n  \"ALLOW_DELETE_OPERATION=false\",\n  \"--\",\n  \"npx\", \"-y\", \"@benborla29\u002Fmcp-server-mysql\"\n]",{"id":141,"question_zh":142,"answer_zh":143,"source_url":121},37402,"为什么在 Cursor 中能正常连接，但在 VSCode Cline 中却报错？","这可能是由于不同编辑器对 MCP 协议的实现细节或环境加载方式不同导致的。如果在 Cursor 中配置直接生效而在 Cline 中失败，建议：\n1. 在 Cline 的配置界面中，明确选择通过 Smithery 安装的模式，而不是手动输入命令。\n2. 检查 Cline 插件是否为最新版本。\n3. 尝试重启 VSCode 以清除可能缓存的错误状态。如果问题持续，可能是 Cline 插件本身的内部兼容性问题，建议向 Cline 开发者反馈。",[145,150,155,160,165,170,175,180,185,189,193,197,201,205,209],{"id":146,"version":147,"summary_zh":148,"released_at":149},297961,"v2.0.8","以下是 MCP 的新增内容及变更说明。\n\n来自 @johnnyee  \n**新增两个用于时区和日期处理配置的环境变量：**\n\n``` \nMYSQL_TIMEZONE：设置日期\u002F时间值的时区\n\n支持的格式包括 +08:00（UTC+8）、-05:00（UTC-5）、Z（UTC）或 local（系统时区）\n有助于确保在不同服务器位置之间实现一致的日期\u002F时间处理\nMYSQL_DATE_STRINGS：当设置为“true”时，将日期\u002Fdatetime 值以字符串形式返回，而非 JavaScript Date 对象\n\n可保留数据库中的精确值，且不进行任何时区转换\n尤其适用于跨时区操作，并避免 JavaScript Date 的一些特殊行为\n```\n\n来自 @triepod-ai  \n为 mysql_query 工具添加了 MCP 工具注解（destructiveHint），以帮助大型语言模型更好地理解工具行为，从而在执行工具时做出更安全的决策。\n\n来自 @veglos  \n根据 [MCP 规范](https:\u002F\u002Fmodelcontextprotocol.io\u002Fspecification\u002F2025-11-25\u002Fschema#toolannotations)，为 `mysql_query` 工具添加了 `ToolAnnotations`。这些注解会通过环境变量动态反映是否启用了写操作。\n\n### 变更内容\n\n- 添加了模块级常量 `isReadOnly`，用于判断服务器是否处于只读模式\n- 在以下两处的工具定义中添加了 `annotations` 对象：\n  - 服务器能力定义（`createMcpServer`）\n  - `ListToolsRequestSchema` 处理器响应\n\n### 注解取值表\n\n| 模式           | `readOnlyHint` | `idempotentHint` | `destructiveHint` | `openWorldHint` |\n|----------------|----------------|------------------|-------------------|-----------------|\n| 只读           | `true`         | `true`           | `false`           | `false`         |\n| 允许写入       | `false`        | `false`          | `true`            | `false`         |\n\n### 设计 rationale\n\n- **`readOnlyHint`**：当未启用任何写操作（`INSERT`、`UPDATE`、`DELETE`、`DDL`）时为 `true`\n- **`idempotentHint`**：在只读模式下，由于 SELECT 查询具有幂等性，因此为 `true`；允许写入时则为 `false`\n- **`destructiveHint`**：当启用写操作（可能修改或删除数据）时为 `true`；在只读模式下则为 `false`\n- **`openWorldHint`**：始终为 `false`——MySQL 数据库是一个封闭、有界的系统（不同于与开放世界交互的网络搜索）。\n\n来自 @addamx：  \n将 `path.resolve()` 替换为 `fs.realpathSync()`，以便在比较之前正确解析符号链接的实际文件路径。\n\n来自 @kelmatiq  \n添加了 Codex CLI 文档。\n\n来自 @aknakshay  \n提供了开箱即用的 SSH 隧道脚本，用于通过堡垒主机连接到私有 VPC 中的 RDS\u002FMySQL 数据库。\n\n## 新增文件\n\n- `scripts\u002Fstart-tunnel-rds.sh` — 通过堡垒主机创建到 RDS 的 SSH 隧道\n- `scripts\u002Fstop-tunnel-rds.sh` — 平稳停止隧道\n- `scripts\u002Ftunnel-config.example` — 配置模板文件\n\n## 功能特性\n\n- 所有参数均可通过环境变量配置（无硬编码密钥）\n- 在尝试连接前会验证所需环境变量是否已设置\n- 能够优雅地处理已运行的隧道\n- 输出清晰，包含连接详情","2026-01-27T14:38:50",{"id":151,"version":152,"summary_zh":153,"released_at":154},297962,"v2.0.7","以下是 MCP 中的新增内容和变更。\n\n来自：@echarrod  \n### **添加连接池保活设置**  \n**新增配置选项**  \n\n- `waitForConnections`: `true` - 当连接池已满时，将连接请求加入队列，而不是立即报错  \n- `queueLimit`: 100（默认值，可配置）- 限制排队请求数量，防止内存无限制增长  \n- `enableKeepAlive`: `true` - 启用 TCP 保活包  \n- `keepAliveInitialDelay`: 0 - 立即开始保活检查  \n- `connectTimeout`: 10000 毫秒（默认值，可配置）- 10 秒连接超时，以提升用户体验  \n\n**环境变量**  \n- `MYSQL_QUEUE_LIMIT` - 覆盖默认的队列限制（默认值：100）  \n- `MYSQL_CONNECT_TIMEOUT` - 覆盖连接超时时间，单位为毫秒（默认值：10000）  \n\n**使用场景**  \n此功能解决了以下情况下的连接稳定性问题：  \n\n- 运行长期运行的 MCP 服务器实例  \n- 通过存在空闲连接超时的代理进行连接  \n- 数据库服务器位于负载均衡器或连接池之后  \n- 网络条件不稳定，存在间歇性连接中断  \n\n----  \n\n来自 @echarrod  \n### 添加 MySQL 连接字符串支持  \n\n**核心实现**  \n连接字符串解析器（src\u002Futils\u002Findex.ts）：  \n\n- 解析 MySQL CLI 格式的连接字符串  \n- 支持短格式标志（`-h`, `-P`, `-u`, `-p`, `-S`）和长格式选项（`--host`, `--port` 等）  \n- 处理带引号的值及复杂密码  \n- 验证端口号范围（1–65535），并检查是否为非数字值  \n\n**配置集成（src\u002Fconfig\u002Findex.ts）：**  \n- 新增对 `MYSQL_CONNECTION_STRING` 环境变量的支持  \n- 连接字符串优先级高于单独的环境变量  \n- 保持与现有配置的向后兼容性  \n- 修复了认证插件中密码回退的一致性问题  \n\n**文档更新**  \n- 更新 `README.md`，增加连接字符串选项说明，并将其定位为替代方案而非主要方式  \n- 补充示例及安全注意事项，提醒不要将连接字符串存储在版本控制系统中  \n- 更新 `.env.dist` 文件，添加连接字符串示例  \n\n-------  \n\n来自 @bulgariamitko  \n### 更正软件包归属信息，并泛化所有示例  \n\n**关键修复内容**  \n\n**🔧 软件包归属信息修正**  \n\n- 将原始软件包名称从 `@bulgariamitko\u002Fmcp-server-mysql-write` 恢复为 `@benborla29\u002Fmcp-server-mysql`  \n- 删除个人 GitHub 用户名引用  \n- 恢复原始作者归属信息，标注为 Ben Borla  \n\n**泛化所有示例**  \n\n- 项目名称：将个人项目名称（nima、izdavam、nufc、studia）替换为通用示例（project-a、project-b、project-c、project-d）  \n- 服务器名称：将个人服务器名称（gold.superhosting.bg、nufc.bg）替换为 example.com 的变体  \n- 数据库名称：将个人数据库名称（izdavamc_、pwr0iwww_）替换为通用格式 db_*  \n- 文件路径：将个人文件路径替换为通用占位符","2025-11-18T09:50:07",{"id":156,"version":157,"summary_zh":158,"released_at":159},297963,"v2.0.5","感谢 @crewsycrews  \n\n- 将 @modelcontextprotocol\u002Fsdk 升级到更高版本，以支持可流式传输的 HTTP 传输。\n- 添加了 express 依赖，以便能够运行一个 HTTP 服务器。\n- 按照这篇 [文档](https:\u002F\u002Fgithub.com\u002Fmodelcontextprotocol\u002Ftypescript-sdk?tab=readme-ov-file#without-session-management-stateless) 实现了远程模式。\n- 在 README 中新增了关于如何设置远程 MCP 的章节。\n- 进行了一些格式化调整（抱歉，我无法阻止我的 IDE 自动进行这些更改）。\n- 修复了 ListResourcesRequestSchema 处理程序，使其能够正确从数据库返回资源列表。\n- 修复了 CallToolRequestSchema 处理程序，使其能够返回错误信息，以便智能体能够理解查询过程中可能出现的问题（如果有的话）。","2025-07-17T15:15:22",{"id":161,"version":162,"summary_zh":163,"released_at":164},297964,"v2.0.3","### 新增功能\n\n- 添加了针对写入和只读查询的性能跟踪（感谢 @paradisecy）\n  - 在代理响应中显示查询时间非常有用，有助于查询优化工作\n- 更新了 README.MD，增加了在 Claude Code 上使用该工具的说明（感谢 @elvismdev）","2025-06-26T05:36:42",{"id":166,"version":167,"summary_zh":168,"released_at":169},297965,"v2.0.0","### 重大新特性 🎉\n\n#### 多数据库权限\n- 新增支持通过单个 MCP 服务器实例管理多个数据库\n- 详细文档请参阅 [MULTI-DB](https:\u002F\u002Fgithub.com\u002Fbenborla\u002Fmcp-server-mysql\u002Fblob\u002Fmain\u002FREADME-MULTI-DB.md)\n- 特别感谢 [@saarthak-gupta-architect](https:\u002F\u002Fgithub.com\u002Fsaarthak-gupta-architect) 的贡献\n- 功能包括：\n  - 动态切换数据库\n  - 跨数据库操作\n  - 针对特定模式的权限控制\n  - 安全的多数据库模式，可选写入保护\n\n### 改进 🔧\n\n#### 增强的日志系统\n- 新增由 `ENABLE_LOGGING` 环境变量控制的可选日志系统\n- 日志级别：信息和错误\n- 在保持输出整洁的同时，提升了调试能力\n- 设置 `ENABLE_LOGGING=1` 启用日志；未设置或设为其他值则禁用\n\n#### 查询处理改进\n- 统一了查询的大小写处理，避免列名大小写敏感问题\n- 所有 SQL 查询在执行前会自动转换为小写\n- 提高了在不同 MySQL 配置下的可靠性\n- 更好地处理大小写敏感的标识符\n\n### 破坏性变更 ⚠️\n\n- 查询处理现在统一使用小写，这可能会影响大小写敏感的数据库配置\n- 日志输出格式已更改——解析服务器输出的应用程序可能需要更新\n- 多数据库支持引入了新的配置选项，现有部署脚本可能需要相应调整\n\n### 迁移指南 🔄\n\n1. 更新环境变量：\n   ```bash\n   # 可选：启用日志\n   ENABLE_LOGGING=1\n\n   # 对于多数据库支持（可选）\n   MULTI_DB_WRITE_MODE=true  # 在多数据库模式下启用写操作\n   ```\n\n2. 检查查询中任何大小写敏感的数据库操作\n3. 更新所有解析服务器输出的脚本，以适应新的日志格式\n4. 如有需要，请查阅 `README-MULTI-DB.md` 中的多数据库设置说明\n\n### 贡献者 👥\n\n特别感谢：\n- [@saarthak-gupta-architect](https:\u002F\u002Fgithub.com\u002Fsaarthak-gupta-architect) —— 多数据库支持\n- [@boyzoid](https:\u002F\u002Fgithub.com\u002Fboyzoid) —— 日志记录","2025-04-03T05:41:46",{"id":171,"version":172,"summary_zh":173,"released_at":174},297966,"v1.0.14","### 增强的测试环境支持\n- 为测试环境添加了自动数据库选择功能\n- 改进了测试检测，更好地支持 Vitest\n- 添加了条件性进程终止机制，以防止测试过早退出\n\n### 修复了数据库连接问题\n- 解决了集成测试期间出现的“未选择数据库”错误\n- 通过提供一致的默认凭据，修复了认证问题\n- 在测试数据库设置中增强了错误处理，使系统更具容错性\n\n### 改进了调试和故障排除\n- 为测试模式下的数据库配置添加了全面的调试日志记录\n- 改进了错误信息，以帮助进行故障排除\n- 为测试专用配置实现了更完善的内联注释\n\n## 破坏性变更\n\n无。本版本保持与先前版本的向后兼容性。\n\n## 已知问题\n\n本版本没有重大已知问题。\n\n## 贡献者\n\n- Ben Borla ([@benborla](https:\u002F\u002Fgithub.com\u002Fbenborla))\n- Lucas Jeeves ([@luca-jeeves](https:\u002F\u002Fgithub.com\u002Fluca-jeeves))\n\n## 链接\n\n- [完整更新日志](https:\u002F\u002Fgithub.com\u002Fbenborla29\u002Fmcp-server-mysql\u002Fblob\u002Fmain\u002FCHANGELOG.md)\n- [NPM 包](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@benborla29\u002Fmcp-server-mysql)","2025-03-29T16:20:05",{"id":176,"version":177,"summary_zh":178,"released_at":179},297967,"v1.0.13","## 新增\n- 通过 Smithery 配置实现完整的写操作支持\n- 新增用于数据库写操作的环境变量（`ALLOW_INSERT_OPERATION`、`ALLOW_UPDATE_OPERATION`、`ALLOW_DELETE_OPERATION`）\n- 在 Smithery 模式中添加了用于控制写权限的新配置选项\n- 改进了写操作配置的相关文档\n- 支持通过环境变量启用或禁用特定的 SQL 操作\n- 增强了对未授权写操作的错误处理\n- 添加了 SSL\u002FTLS 配置选项（感谢 @luca-jeeves）\n\n## 变更\n- 更新了 Smithery 配置，加入了写操作设置\n- 改进了 Smithery 的集成，设置了清晰的安全默认值\n- 丰富了文档内容，提供了详细的配置示例\n- 重新组织了 README 文件，使安装说明更加清晰\n- 改进了数据库连接问题的错误报告\n- 优化了写操作的事务处理\n\n## 修复\n- 修复了数据库连接失败时的错误处理逻辑\n- 改进了未授权操作的错误提示信息\n- 更好地兼容 MySQL 8.0 及以上版本的身份验证方式\n\n## 安全性\n- 默认禁用所有写操作（INSERT、UPDATE、DELETE）\n- 添加了关于启用写操作可能带来的安全影响的明确说明\n- 提升了写操作的事务隔离级别\n- 加强了错误报告机制，避免泄露敏感信息\n\n## 文档\n- 更新了 README 文件，增加了全面的 Smithery 配置说明\n- 添加了启用特定写操作的详细示例\n- 改进了故障排除部分，列出了常见问题及解决方案\n- 更清晰地解释了不同操作类型所需的 MySQL 权限\n- 增加了针对生产环境部署的安全建议","2025-03-29T14:55:08",{"id":181,"version":182,"summary_zh":183,"released_at":184},297968,"v1.0.8","增加了锻造厂支持  \n增加了 Docker 支持","2025-01-28T00:40:56",{"id":186,"version":187,"summary_zh":80,"released_at":188},297969,"v1.0.7","2024-12-09T18:45:02",{"id":190,"version":191,"summary_zh":80,"released_at":192},297970,"v1.0.5","2024-12-09T18:11:52",{"id":194,"version":195,"summary_zh":80,"released_at":196},297971,"v1.0.4","2024-12-09T17:01:24",{"id":198,"version":199,"summary_zh":80,"released_at":200},297972,"v1.0.3","2024-12-09T16:37:28",{"id":202,"version":203,"summary_zh":80,"released_at":204},297973,"v1.0.2","2024-12-09T16:35:09",{"id":206,"version":207,"summary_zh":80,"released_at":208},297974,"v1.0.1","2024-12-09T16:30:06",{"id":210,"version":211,"summary_zh":80,"released_at":212},297975,"v1.0.0","2024-12-09T14:42:04"]