SQL Server MCP (macOS)

SQL Server MCP - 面向 AI 的跨平台数据库集成

面向 SQL Server 的 Model Context Protocol (MCP) 服务实现，可让 AI 助手通过自然语言探索和查询 SQL Server 数据库。该项目基于专为数据库知识探索优化的 RAG（检索增强生成）系统构建。

🌟 功能

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

🎥 演示

查看 SQL Server MCP 与 AI 助手集成后的运行效果：

注意： 查看自然语言查询如何即时探索数据库架构、查找关系并检索数据，全程无需离开 AI 助手！

🚀 快速开始

此仓库包含两个平台专用实现：

Windows 版本 → sql-server-mcp/

• ✅ Windows 身份验证（ODBC Driver 17）
• ✅ SQL Server 身份验证
• ✅ 原生 msnodesqlv8 驱动程序，性能出色
• 📖 Windows 设置指南

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

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

📦 安装

🎉 现已上架 MCP Registry！

此服务已正式发布到 Model Context Protocol Registry：

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

🚀 快速开始（推荐）

无需安装！只需将其添加到 AI 助手的配置中：

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"
      }
    }
  }
}

重启 AI 助手，即可开始使用！

🛠️ 开发环境设置

用于开发或本地修改：

Windows

cd sql-server-mcp
npm install
npm run build

👉 Windows 完整设置说明

macOS

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

👉 macOS 完整设置说明

🛠️ 可用的 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 查询

💬 使用示例

配置完成后，你可以向 AI 助手提问：

"What databases are available on this server?"

"Show me all tables in the Sales database"

"What's the schema of the Orders table?"

"Find all tables that reference the Customers table"

"Search for any columns related to 'email'"

"Execute: SELECT TOP 10 * FROM Products ORDER BY Price DESC"

⚙️ 配置

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

SQL_SERVER=localhost
SQL_DATABASE=master
SQL_PORT=1433
SQL_USE_WINDOWS_AUTH=true          # Windows only
SQL_USERNAME=                       # For SQL Auth
SQL_PASSWORD=                       # For SQL Auth
QUERY_TIMEOUT=30
MAX_RESULT_ROWS=1000
ENABLE_SCHEMA_CACHE=true
CACHE_TTL_MINUTES=60

详细配置说明请参阅对应平台的 README。

🔐 安全功能

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

🏗️ 架构

MCP/
├── sql-server-mcp/              # Windows implementation
│   ├── src/
│   │   ├── index.ts             # MCP server entry point
│   │   ├── database/            # Connection, caching, queries
│   │   ├── tools/               # 12 MCP tools
│   │   └── types/               # TypeScript interfaces
│   ├── dist/                    # Compiled output
│   ├── package.json
│   └── README.md                # Windows documentation
│
├── sql-server-mcp-mac/          # macOS implementation
│   ├── src/                     # Same structure as Windows
│   └── README.md                # macOS documentation
│
├── LICENSE                      # MIT License
└── README.md                    # This file

🎯 使用场景

数据库探索

• “此数据库中有哪些表？”
• “向我展示 Users 表的结构”
• “列出所有存储过程”

架构研究

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

关系分析

• “Orders 和 Customers 之间有什么关系？”
• “向我展示所有引用 Products 的表”
• “此表有哪些外键关系？”

数据查询

• “获取价格最高的 10 种产品”
• “向我展示最近的订单”
• “每个表中的记录总数是多少？”

🤝 参与贡献

欢迎贡献！请随时提交 Pull Request。对于重大更改，请先提交 issue，讨论你希望进行的更改。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🙏 致谢

• 基于 Model Context Protocol SDK 构建
• 使用 mssql 和 msnodesqlv8 驱动程序
• 灵感来自对更完善的 AI 与数据库集成方案的需求

📚 资源

• 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

🌐 平台专属文档

为 MCP 社区倾心打造 ❤️

⭐ 如果你觉得这个仓库有用，请点 Star！ 🐛 请通过 Issues 报告错误 💬 有疑问？ 请查看 Discussions