sql-mcp-mac-windows

🚀 SQL Server MCP - 用于人工智能的跨平台数据库集成

SQL Server MCP 是一个基于 Model Context Protocol (MCP) 的服务器实现，它使人工智能助手能够通过自然语言探索和查询 SQL Server 数据库。该系统作为一个专为数据库知识探索优化的 RAG（检索增强生成）系统构建。

🚀 快速开始

本仓库包含两个特定平台的实现：

Windows 版本 → sql-server-mcp/

• ✅ Windows 身份验证（ODBC 驱动 17）
• ✅ SQL Server 身份验证
• ✅ 原生 msnodesqlv8 驱动以实现最佳性能
• 📖 Windows 安装指南

macOS 版本 → sql-server-mcp-mac/

• ✅ SQL Server 身份验证（需要 Docker）
• ✅ 纯 JavaScript mssql 驱动（无原生依赖）
• 📖 macOS 安装指南

✨ 主要特性

• 🔍 模式探索 - 列出数据库、表、视图、存储过程
• 🔗 关系映射 - 发现外键关系和表依赖
• 🔎 搜索与发现 - 跨表、列、过程进行全局模式搜索
• ⚡ 安全查询执行 - 具有自动超时和行限制的只读 SELECT 查询
• 🗄️ 模式缓存 - 可配置 TTL 的快速检索（默认：60 分钟）
• 🔐 安全至上 - 默认只读，防止 SQL 注入，查询验证
• 🖥️ 跨平台 - 原生 Windows 身份验证和 macOS Docker 支持

🎥 演示

查看 SQL Server MCP 与人工智能助手集成的实际操作：

注意：观看自然语言查询如何立即探索数据库模式、查找关系并检索数据 - 所有操作都无需离开你的人工智能助手！

📦 安装指南

🎉 现已在 MCP 注册表中可用！

此服务器已正式发布在 Model Context Protocol 注册表 中：

• Windows：io.github.TharanaBope/sql-server-mcp
• macOS：io.github.TharanaBope/sql-server-mcp-macos

🚀 快速开始（推荐）

无需安装！只需将其添加到你的人工智能助手配置中：

Claude Desktop（Windows）

配置位置：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sql-server": {
      "command": "npx",
      "args": ["-y", "@tharanabopearachchi/sql-server-mcp@latest"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "master",
        "SQL_USE_WINDOWS_AUTH": "true"
      }
    }
  }
}

Claude Desktop（macOS）

配置位置：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sql-server": {
      "command": "npx",
      "args": ["-y", "@tharanabopearachchi/sql-server-mcp-macos@latest"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "master",
        "SQL_USE_WINDOWS_AUTH": "false",
        "SQL_USERNAME": "sa",
        "SQL_PASSWORD": "your_password"
      }
    }
  }
}

{
  "mcpServers": {
    "sql-server": {
      "command": "npx",
      "args": ["-y", "@tharanabopearachchi/sql-server-mcp@latest"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "master",
        "SQL_USE_WINDOWS_AUTH": "true",
        "SQL_USERNAME": "",
        "SQL_PASSWORD": ""
      }
    }
  }
}

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@tharanabopearachchi/sql-server-mcp@latest"]
        },
        "env": {
          "SQL_SERVER": "localhost",
          "SQL_DATABASE": "master",
          "SQL_USE_WINDOWS_AUTH": "true"
        }
      }
    ]
  }
}

{
  "mcpServers": {
    "sql-server": {
      "command": "npx",
      "args": ["-y", "@tharanabopearachchi/sql-server-mcp@latest"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "master",
        "SQL_USE_WINDOWS_AUTH": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "sql-server": {
      "command": "npx",
      "args": ["-y", "@tharanabopearachchi/sql-server-mcp@latest"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "master",
        "SQL_USE_WINDOWS_AUTH": "true"
      }
    }
  }
}

重启你的人工智能助手，即可开始使用！

🛠️ 开发设置

对于开发或本地修改：

Windows

cd sql-server-mcp
npm install
npm run build

👉 完整的 Windows 设置说明

macOS

cd sql-server-mcp-mac
npm install
npm run build

👉 完整的 macOS 设置说明

💻 使用示例

配置完成后，你可以向你的人工智能助手提问：

"此服务器上有哪些数据库可用？"

"显示 Sales 数据库中的所有表"

"Orders 表的模式是什么？"

"查找所有引用 Customers 表的表"

"搜索与 'email' 相关的任何列"

"执行：SELECT TOP 10 * FROM Products ORDER BY Price DESC"

📚 详细文档

🛠️ 可用的 MCP 工具

该服务器提供了 12 个强大的数据库探索工具：

模式探索

• list_databases - 发现所有可用的数据库
• list_tables - 查看带有行数的表
• describe_table - 获取详细的模式（列、类型、约束、索引）
• list_views - 列出所有视图
• list_stored_procedures - 列出带有元数据的存储过程
• get_procedure_definition - 获取完整的 SQL 定义
• get_database_overview - 高级统计信息

关系映射

• get_table_relationships - 获取外键关系（传入和传出）
• get_related_tables - 查找直接连接的表

搜索与发现

• search_schema - 跨表、列、视图、过程进行搜索
• find_column_usage - 查找包含特定列的所有表

查询执行

• execute_query - 安全地执行只读 SELECT 查询

⚙️ 配置

两个版本都使用环境变量进行配置：

SQL_SERVER=localhost
SQL_DATABASE=master
SQL_PORT=1433
SQL_USE_WINDOWS_AUTH=true          # 仅适用于 Windows
SQL_USERNAME=                       # 用于 SQL 身份验证
SQL_PASSWORD=                       # 用于 SQL 身份验证
QUERY_TIMEOUT=30
MAX_RESULT_ROWS=1000
ENABLE_SCHEMA_CACHE=true
CACHE_TTL_MINUTES=60

有关详细的配置说明，请参阅特定平台的 README 文件。

🔐 安全特性

• ✅ 默认只读 - 除非明确启用，否则禁用写操作
• ✅ 查询验证 - 默认只允许 SELECT 语句
• ✅ 自动超时 - 防止长时间运行的查询
• ✅ 行限制 - 防止内存耗尽
• ✅ 防止 SQL 注入 - 查询清理和验证
• ✅ 数据库白名单 - 可选限制到特定数据库

🏗️ 架构

MCP/
├── sql-server-mcp/              # Windows 实现
│   ├── src/
│   │   ├── index.ts             # MCP 服务器入口点
│   │   ├── database/            # 连接、缓存、查询
│   │   ├── tools/               # 12 个 MCP 工具
│   │   └── types/               # TypeScript 接口
│   ├── dist/                    # 编译输出
│   ├── package.json
│   └── README.md                # Windows 文档
│
├── sql-server-mcp-mac/          # macOS 实现
│   ├── src/                     # 与 Windows 结构相同
│   └── README.md                # macOS 文档
│
├── LICENSE                      # MIT 许可证
└── README.md                    # 此文件

🎯 使用场景

数据库探索

• "此数据库中存在哪些表？"
• "显示 Users 表的结构"
• "列出所有存储过程"

模式研究

• "查找所有包含 'email' 列的表"
• "搜索与 'invoice' 相关的任何内容"
• "有哪些视图可用？"

关系分析

• "Orders 和 Customers 之间有什么关系？"
• "显示所有引用 Products 表的表"
• "此表的外键关系是什么？"

数据查询

• "获取前 10 个最昂贵的产品"
• "显示最近的订单"
• "每个表中的记录总数是多少？"

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

🙏 致谢

• 基于 Model Context Protocol SDK 构建
• 使用 mssql 和 msnodesqlv8 驱动
• 受更好的人工智能与数据库集成需求的启发

📚 资源

• Windows 安装指南：sql-server-mcp/README.md
• macOS 安装指南：sql-server-mcp-mac/README.md
• 故障排除：查看特定平台的 TROUBLESHOOTING.md 文件
• MCP 文档：https://github.com/modelcontextprotocol
• 报告问题：https://github.com/TharanaBope/SQL-MCP-Mac-Windows/issues

🌐 特定平台文档

| 平台 | 目录 | 主要特性 | |----------|-----------|--------------| | Windows | sql-server-mcp/ | Windows 身份验证、ODBC 驱动、原生性能 | | macOS | sql-server-mcp-mac/ | Docker SQL Server、纯 JavaScript、无原生依赖 |

为 MCP 社区用心打造 ❤️

⭐ 如果你觉得有用，请给这个仓库加星！ 🐛 通过 问题 报告错误 💬 有问题？ 查看 讨论