MS SQL Server MCP 服务器

本项目提供了一个 MCP 服务器，用于通过使用模型上下文协议 (MCP) 的 AI 助手与 MS SQL Server 数据库进行交互。

它使用安全的配置文件管理系统，利用系统原生的凭据存储（通过 keyring 库）来避免通过 MCP 发送密码。

前提条件

对于直接 Python 执行：

• Python 3.10+
• Pip (Python 包安装程序)
• 安装在运行服务器的机器上的 SQL Server ODBC 驱动程序。
• keyring 库依赖项可能需要系统软件包（例如，Linux 上的 dbus-launch、gnome-keyring 或 kwallet，有关详细信息，请参阅 keyring 文档）。

对于 Docker 执行：

• 已安装并运行的 Docker。
• Dockerfile 配置为使用 keyrings.cryptfile 后端，以便在容器的文件系统中安全地存储密码。 这需要挂载卷以实现持久性。

安装

选项 1：直接 Python 执行

1. 克隆存储库（如果适用）：

   git clone <repository_url>
   cd mcp-server-mssql
   

2. 创建并激活 Python 虚拟环境：

   python -m venv venv
   # 激活 (Windows PowerShell): .\venv\Scripts\Activate.ps1
   # 激活 (macOS/Linux): source venv/bin/activate
   

3. 安装依赖项：

   pip install -r requirements.txt
   

选项 2：Docker 执行

1. 克隆存储库（如果适用）。
2. 构建 Docker 镜像：

   docker build -t mcp-mssql-server .
   

   (注意：Dockerfile 包括 ODBC 驱动程序安装并配置 keyrings.cryptfile 后端。)

配置：配置文件管理

此服务器使用连接配置文件来安全地管理数据库凭据。

1. 配置文件 (profiles.json)： 在服务器的目录中本地存储非敏感详细信息（驱动程序、服务器、数据库、用户名）。 如果此文件不存在，则会自动创建。 确保将此文件添加到您的 .gitignore 中。
2. 系统密钥环： 密码使用 keyring 库，以服务名称 mcp-mssql-server 安全地存储在您的操作系统凭据管理器（如 Windows 凭据管理器、macOS Keychain）中。
3. 添加配置文件： 使用 add_connection_profile 工具。 首次添加配置文件时，系统将提示您在服务器运行的终端中安全地输入密码。 此密码永远不会通过 MCP 发送。
4. 管理配置文件： 使用 list_connection_profiles 和 remove_connection_profile 工具。

用法

选项 1：直接 Python 执行 (Stdio)

1. 激活虚拟环境。
2. 在 MCP 客户端设置中配置（例如，mcp_settings.json）：

   {
     "mcpServers": {
       // ... 其他服务器 ...
       "mssql": {
         "command": "python", // 或 venv python 的完整路径
         "args": ["D:/path/to/your/mcp-server-mssql/server.py"],
         "cwd": "D:/path/to/your/mcp-server-mssql",
         "alwaysAllow": [
           "add_connection_profile",
           "list_connection_profiles",
           "remove_connection_profile",
           "read_table_rows",
           "create_table_records",
           "update_table_records",
           "delete_table_records",
           "get_table_schema",
           "list_tables"
         ]
       }
       // ... 其他服务器 ...
     }
   }
   

   相应地调整路径。
3. 重新启动您的 MCP 客户端/IDE 扩展。 使用 add_connection_profile 工具添加配置文件（需要控制台交互才能输入密码）。

选项 2：Docker 执行 (Stdio)

1. 确保已构建 Docker 镜像 mcp-mssql-server。
2. 在 MCP 客户端设置中配置：

   {
     "mcpServers": {
       // ... 其他服务器 ...
       "mssql-docker": {
         "command": "docker",
         "args": [
           "run", "-i", "--rm",
           "--env-file", "./mcp-server-mssql/.env_docker", // 示例：在此处存储 KEYRING_CRYPTFILE_PASSWORD
           "-v", "mssql_keyring_data:/keyring_data", // 挂载卷以存储密钥环数据
           "mcp-mssql-server"
         ],
         "alwaysAllow": [
           "add_connection_profile", // 注意：密码提示将出现在容器日志中
           "list_connection_profiles",
           "remove_connection_profile",
           "read_table_rows",
           "create_table_records",
           "update_table_records",
           "delete_table_records",
           "get_table_schema",
           "list_tables"
         ]
       }
       // ... 其他服务器 ...
     }
   }
   

3. 重新启动您的 MCP 客户端/IDE 扩展。
4. 重要：
   • Dockerfile 配置为使用 keyrings.cryptfile 后端。 您必须提供一个强密码，用于在运行容器时通过 KEYRING_CRYPTFILE_PASSWORD 环境变量加密密钥环文件。 强烈建议使用 .env 文件（如 args 中的示例 .env_docker）或 Docker secrets，而不是直接在命令行上传递密码。
   • 必须将 Docker 卷（例如，示例中的 mssql_keyring_data）挂载到容器内的 /keyring_data，以便在容器重启后持久保存加密的密钥环文件 (keyring_pass.cfg) 和 profiles.json 文件。
   • add_connection_profile 密码提示仍将出现在容器的日志/终端中。

可用工具

配置文件管理：

• add_connection_profile(profile_name: str, driver: str, server: str, database: str, username: str)
• list_connection_profiles()
• remove_connection_profile(profile_name: str)

数据库操作（需要 profile_name）：

• read_table_rows(profile_name: str, table_name: str, ...)
• create_table_records(profile_name: str, table_name: str, records: List[Dict])
• update_table_records(profile_name: str, table_name: str, updates: Dict, filters: Dict)
• delete_table_records(profile_name: str, table_name: str, filters: Dict)
• get_table_schema(profile_name: str, table_name: str)
• list_tables(profile_name: str, schema: Optional[str] = None)

有关详细的参数说明，请参阅 server.py 中的文档字符串。

示例工具用法（概念性）

1. 添加配置文件（需要在服务器上进行控制台交互）： “使用 mssql 服务器，调用 add_connection_profile，名称为 SalesDB_UK，驱动程序为 {ODBC Driver 17 for SQL Server}，服务器为 myserver.example.com，数据库为 SalesDB，用户名为 report_user。”（然后在服务器控制台中输入密码）。
2. 使用配置文件： “使用 mssql 服务器，使用配置文件 SalesDB_UK 调用 read_table_rows，用于表 Customers。 筛选条件为 Country 为 'UK'。”

AI 助手将构建第二个调用，如下所示：

// 概念性 MCP 工具调用
{
  "tool_name": "read_table_rows",
  "arguments": {
    "profile_name": "SalesDB_UK",
    "table_name": "Customers",
    "filters": {
      "Country": "UK"
    }
  }
}