MSSQL Server MCP 服务器

一个功能强大的基于 Model Context Protocol (MCP) 的 MSSQL Server 服务器，提供企业级 DDL 支持、细粒度权限控制、全面的操作日志记录和智能连接池管理。

🚀 核心功能特性

$3

- 完整 SQL 支持: 支持 DDL 和 DML 操作，具备 SQL 注入防护
- 高级权限控制: 通过环境变量对 DDL、DROP、DELETE 操作进行细粒度控制
- 全面日志记录: 完整的请求响应日志、SQL 操作跟踪和连接池监控
- 企业级连接管理: 自动连接池创建、健康监控和故障恢复
- MCP 协议兼容: 完整的 Model Context Protocol 实现，支持工具发现和执行
- 多编辑器支持: 与 Cursor、VS Code 等 MCP 兼容编辑器无缝集成

$3

- 架构自动前缀: 多租户环境的自动架构处理
- 连接池优化: 智能连接复用和性能调优
- 错误处理: 全面的错误日志记录和优雅的故障恢复
- 安全特性: SQL 注入防护、参数化查询支持和操作验证

📦 安装

$3

#### 全局安装（推荐）
``bash
npm install -g @liangshanli/mcp-server-mssqlserver
`

#### 本地安装
`bash
npm install @liangshanli/mcp-server-mssqlserver
`

$3

`bash
git clone https://github.com/liliangshan/mcp-server-mssqlserver.git
cd mcp-server-mssqlserver
npm install
`

⚙️ 配置

$3

#### 数据库连接设置
| 环境变量 | 默认值 | 描述 | 必需 |
|---------|--------|------|------|
| MSSQL_SERVER | localhost | MSSQL Server 主机地址 | ✅ |
| MSSQL_PORT | 1433 | MSSQL Server 端口号 | ✅ |
| MSSQL_USER | sa | 数据库用户名 | ✅ |
| MSSQL_PASSWORD | | 数据库密码 | ✅ |
| MSSQL_DATABASE | | 目标数据库名称 | ✅ |
| MSSQL_SCHEMA | dbo | 默认架构名称 | ✅ |
| MSSQL_ENCRYPT | false | 启用加密 | ❌ |
| MSSQL_TRUST_SERVER_CERTIFICATE | true | 信任服务器证书 | ❌ |

#### 权限控制设置
| 环境变量 | 默认值 | 描述 | 安全级别 |
|---------|--------|------|----------|
| ALLOW_DDL | false | 允许 CREATE、ALTER、DROP 操作 | 🔴 高风险 |
| ALLOW_DROP | false | 允许 DROP TABLE 操作 | 🔴 高风险 |
| ALLOW_DELETE | false | 允许 DELETE 操作 | 🟡 中风险 |

#### 日志配置
| 环境变量 | 默认值 | 描述 |
|---------|--------|------|
| MCP_LOG_DIR | ./logs | 日志目录路径 |
| MCP_LOG_FILE | mcp-mssqlserver.log | 日志文件名 |

$3

#### 开发环境（高权限）
`bash
export ALLOW_DDL=true
export ALLOW_DROP=true
export ALLOW_DELETE=true
`

#### 测试环境（中等权限）
`bash
export ALLOW_DDL=true
export ALLOW_DROP=false
export ALLOW_DELETE=true
`

#### 生产环境（限制权限）
`bash
export ALLOW_DDL=false
export ALLOW_DROP=false
export ALLOW_DELETE=false
`

🚀 使用方法

$3

#### 方式 1: CLI 启动
`bash
npm start
`

#### 方式 2: 直接运行服务器
`bash
npm run server
`

#### 方式 3: 托管模式启动
`bash
npm run start-managed
`

#### 方式 4: 开发模式启动（带调试）
`bash
npm run dev
`

$3

`bash

数据库连接

export MSSQL_SERVER=your-mssql-server.com
export MSSQL_PORT=1433
export MSSQL_USER=your-username
export MSSQL_PASSWORD=your-secure-password
export MSSQL_DATABASE=your-database
export MSSQL_SCHEMA=your-schema

安全权限

export ALLOW_DDL=true
export ALLOW_DROP=false
export ALLOW_DELETE=true

日志配置

export MCP_LOG_DIR=/var/log/mcp
export MCP_LOG_FILE=mssqlserver.log

启动服务器

npm start
`

🛠️ 可用工具

$3

执行 SQL 查询，支持完整的 DDL 和 DML 操作。

参数:
- sql (string, 必需): 要执行的 SQL 语句

特性:
- 自动架构前缀处理
- 权限验证
- 全面错误处理
- SQL 注入防护

示例:
`json
{
"name": "sql_query",
"arguments": {
"sql": "SELECT * FROM users WHERE id = 1"
}
}
`

支持的操作:
- ✅ SELECT 查询
- ✅ INSERT 操作
- ✅ UPDATE 操作
- ✅ DELETE 操作（如果允许）
- ✅ CREATE TABLE（如果 DDL 允许）
- ✅ ALTER TABLE（如果 DDL 允许）
- ✅ DROP TABLE（如果 DROP 允许）

$3

获取全面的数据库信息和配置详情。

参数: 无

返回信息:
- 数据库列表
- 当前数据库的表列表
- 当前配置
- 权限状态
- 连接信息

示例:
`json
{
"name": "get_database_info",
"arguments": {}
}
`

$3

访问详细的操作日志，用于监控和调试。

参数:
- limit (number, 可选): 返回的日志条目数量（默认: 50）
- offset (number, 可选): 分页起始位置（默认: 0）

日志信息:
- 请求/响应详情
- SQL 执行结果
- 错误消息和堆栈跟踪
- 连接池状态
- 性能指标

示例:
`json
{
"name": "get_operation_logs",
"arguments": {
"limit": 100,
"offset": 0
}
}
`

$3

验证当前权限配置和访问权限。

参数: 无

返回信息:
- 当前权限设置
- 环境变量状态
- 配置验证
- 安全建议

示例:
`json
{
"name": "check_permissions",
"arguments": {}
}
`

📊 日志记录和监控

$3

#### 1. 请求/响应日志
- 所有 MCP 方法调用
- 参数验证
- 响应生成
- 错误处理

#### 2. SQL 操作日志
- SQL 语句执行
- 查询结果
- 性能指标
- 错误详情

#### 3. 连接池日志
- 池创建/销毁
- 健康检查结果
- 连接失败
- 恢复尝试

#### 4. 系统事件日志
- 服务器启动/关闭
- 配置更改
- 权限更新
- 安全事件

$3

- 默认: ./logs/mcp-mssqlserver.log
- 可自定义: 通过 MCP_LOG_DIR 和 MCP_LOG_FILE 环境变量

$3

`
2025-01-15T10:30:00.000Z | method_name | {"param1": "value1"} | SUCCESS | RESPONSE: {"result": "data"}
2025-01-15T10:30:01.000Z | SQL: SELECT * FROM users | SUCCESS
`

🔒 安全特性

$3

- 细粒度访问控制: 对不同操作类型的精细权限管理
- 基于环境的安全: 通过环境变量进行安全配置
- 操作验证: SQL 执行前实时权限检查
- 审计日志: 所有操作的完整审计跟踪

$3

- 参数化查询: 支持预处理语句
- 输入验证: 全面的输入清理
- 错误屏蔽: 安全的错误消息处理
- 查询日志: 完整的 SQL 操作跟踪

$3

- 加密连接: 支持 SSL/TLS 加密
- 证书验证: 可配置的证书信任设置
- 连接池: 安全的连接管理
- 超时保护: 可配置的连接和请求超时

🎯 编辑器集成

$3

1. 在项目根目录创建 .cursor/mcp.json 文件：

`json
{
"mcpServers": {
"mssqlserver": {
"command": "npx",
"args": ["@liangshanli/mcp-server-mssqlserver"],
"env": {
"MSSQL_SERVER": "your_host",
"MSSQL_PORT": "1433",
"MSSQL_USER": "your_user",
"MSSQL_PASSWORD": "your_password",
"MSSQL_DATABASE": "your_database",
"MSSQL_SCHEMA": "your_schema",
"MSSQL_ENCRYPT": "false",
"MSSQL_TRUST_SERVER_CERTIFICATE": "true",
"ALLOW_DDL": "false",
"ALLOW_DROP": "false",
"ALLOW_DELETE": "false"
}
}
}
}
`

$3

1. 安装 VS Code 的 MCP 扩展
2. 创建 .vscode/settings.json 文件：

`json
{
"mcp.servers": {
"mssqlserver": {
"command": "npx",
"args": ["@liangshanli/mcp-server-mssqlserver"],
"env": {
"MSSQL_SERVER": "your_host",
"MSSQL_PORT": "1433",
"MSSQL_USER": "your_user",
"MSSQL_PASSWORD": "your_password",
"MSSQL_DATABASE": "your_database",
"MSSQL_SCHEMA": "your_schema",
"MSSQL_ENCRYPT": "false",
"MSSQL_TRUST_SERVER_CERTIFICATE": "true",
"ALLOW_DDL": "false",
"ALLOW_DROP": "false",
"ALLOW_DELETE": "false"
}
}
}
}
`

$3

服务器通过 stdin/stdout 与 MCP 客户端通信：

`json
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18"}}
`

🔧 连接池管理

$3

- 自动创建: 在 notifications/initialized 时自动创建连接池
- 健康监控: 5分钟间隔的健康检查
- 自动恢复: 失败时自动重新创建池
- 性能优化: 智能连接复用
- 优雅关闭: 服务器终止时正确清理连接

$3

- 池大小: 可配置的最小和最大连接数
- 超时设置: 可自定义的连接和请求超时
- 重试逻辑: 失败连接的可配置重试尝试
- 负载均衡: 智能连接分发

🚨 故障排除

$3

#### 1. 连接失败
症状:
- "Connection refused" 错误
- 超时错误
- 认证失败

解决方案:
- 验证 MSSQL Server 是否运行
- 检查防火墙设置
- 验证连接参数
- 确认网络连接性

#### 2. 权限错误
症状:
- "Operation not allowed" 错误
- "Access denied" 消息
- 权限验证失败

解决方案:
- 检查环境变量配置
- 验证数据库用户权限
- 确认 ALLOW_* 设置
- 审查安全配置

#### 3. 日志问题
症状:
- 缺少日志文件
- 不完整的日志条目
- 权限被拒绝错误

解决方案:
- 检查日志目录权限
- 验证磁盘空间可用性
- 确认日志文件路径有效性
- 审查文件系统权限

$3

启用详细的调试信息：

`bash
npm run dev
`

调试信息:
- 详细的 SQL 执行日志
- 连接池状态
- 权限验证详情
- 错误堆栈跟踪
- 性能指标

🏗️ 开发

$3

`
mcp-server-mssqlserver/
├── bin/
│ └── cli.js # CLI 启动脚本
├── src/
│ └── server-final.js # 主要服务器实现
├── start-server.js # 托管启动脚本
├── package.json # 项目配置
├── README.md # 英文文档
├── README.zh-CN.md # 中文文档
└── SCHEMA_USAGE.md # 架构使用指南
`

$3

`bash

安装依赖

npm install

运行基本测试

npm test

运行全面测试

npm run test-full

启动开发服务器

npm run dev

生产环境构建

npm run build
``

$3

- 热重载: 代码更改时自动服务器重启
- 调试日志: 全面的调试信息
- 错误处理: 详细的错误报告和堆栈跟踪
- 性能监控: 实时性能指标

📄 许可证

MIT License - 详情请参阅 LICENSE 文件

🤝 贡献

我们欢迎贡献！请参阅我们的贡献指南：

1. Fork 仓库
2. 创建功能分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

$3

- 错误修复: 报告和修复错误
- 功能开发: 添加新功能
- 文档: 改进文档
- 测试: 添加测试覆盖
- 性能: 优化性能

🔗 相关链接

- Model Context Protocol - 官方 MCP 规范
- MSSQL Node.js Driver - 数据库驱动文档
- MCP Specification - 完整协议文档
- GitHub Repository - 源代码和问题

📞 支持

$3

- GitHub Issues: 报告错误和请求功能
- 文档: 全面的指南和示例
- 示例: 工作示例和用例
- 社区: 加入我们的开发者社区

$3

- Node.js: 18.x 或更高版本
- MSSQL Server: 2012 或更高版本
- MCP Protocol: 2025-06-18 或兼容版本

💡 使用场景

$3

- 为开发人员提供安全的数据库访问接口
- 支持完整的 DDL 操作进行表结构设计
- 详细的日志记录帮助调试和问题排查

$3

- 支持自动化测试和数据库操作验证
- 限制危险操作权限保护测试数据
- 完整的操作审计跟踪

$3

- 通过严格的权限控制保护生产数据库
- 企业级连接池管理确保高可用性
- 全面的安全防护和监控

$3

- 为 AI 工具提供安全的数据库操作能力
- 支持自然语言到 SQL 的转换
- 智能权限管理和操作验证

🔐 安全最佳实践

$3

- 开发阶段: 启用所有权限进行功能测试
- 测试阶段: 限制 DROP 操作，允许 DDL 和 DELETE
- 预生产: 严格限制所有危险操作权限
- 生产环境: 仅允许必要的查询操作

$3

- 使用防火墙限制数据库访问
- 启用 SSL/TLS 加密连接
- 定期更新数据库用户密码
- 监控异常访问模式

$3

- 启用完整的操作日志记录
- 定期审查权限配置
- 监控数据库性能指标
- 设置告警机制