@liangshanli/mcp-server-mssqlserver

v2.0.1

Published

4 months ago

MCP MSSQL Server with DDL support, permission control and operation logs

0High
0Medium
0Low

liangshanli1983

mcp mssql sqlserver server ddl database

MSSQL Server MCP 服务器

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

🚀 核心功能特性

主要能力

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

高级特性

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

📦 安装

NPM 安装

全局安装（推荐）

npm install -g @liangshanli/mcp-server-mssqlserver

本地安装

npm install @liangshanli/mcp-server-mssqlserver

手动安装

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

⚙️ 配置

环境变量

数据库连接设置

| 环境变量 | 默认值 | 描述 | 必需 | |---------|--------|------|------| | 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 | 日志文件名 |

安全配置示例

开发环境（高权限）

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

测试环境（中等权限）

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

生产环境（限制权限）

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

🚀 使用方法

启动服务器

方式 1: CLI 启动

npm start

方式 2: 直接运行服务器

npm run server

方式 3: 托管模式启动

npm run start-managed

方式 4: 开发模式启动（带调试）

npm run dev

完整环境设置示例

# 数据库连接
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

🛠️ 可用工具

1. sql_query

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

参数:

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

特性:

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

示例:

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

支持的操作:

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

2. get_database_info

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

参数: 无

返回信息:

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

示例:

{
  "name": "get_database_info",
  "arguments": {}
}

3. get_operation_logs

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

参数:

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

日志信息:

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

示例:

{
  "name": "get_operation_logs",
  "arguments": {
    "limit": 100,
    "offset": 0
  }
}

4. check_permissions

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

参数: 无

返回信息:

当前权限设置
环境变量状态
配置验证
安全建议

示例:

{
  "name": "check_permissions",
  "arguments": {}
}

📊 日志记录和监控

日志分类

1. 请求/响应日志

所有 MCP 方法调用
参数验证
响应生成
错误处理

2. SQL 操作日志

SQL 语句执行
查询结果
性能指标
错误详情

3. 连接池日志

池创建/销毁
健康检查结果
连接失败
恢复尝试

4. 系统事件日志

服务器启动/关闭
配置更改
权限更新
安全事件

日志文件位置

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

日志格式

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

🔒 安全特性

权限控制

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

SQL 注入防护

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

连接安全

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

🎯 编辑器集成

Cursor 编辑器配置

在项目根目录创建 .cursor/mcp.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"
      }
    }
  }
}

VS Code 配置

安装 VS Code 的 MCP 扩展
创建 .vscode/settings.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"
      }
    }
  }
}

直接使用 MCP 服务器

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

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

🔧 连接池管理

自动特性

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

配置选项

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

🚨 故障排除

常见问题

1. 连接失败

症状:

"Connection refused" 错误
超时错误
认证失败

解决方案:

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

2. 权限错误

症状:

"Operation not allowed" 错误
"Access denied" 消息
权限验证失败

解决方案:

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

3. 日志问题

症状:

缺少日志文件
不完整的日志条目
权限被拒绝错误

解决方案:

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

调试模式

启用详细的调试信息：

npm run dev

调试信息:

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

🏗️ 开发

项目结构

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        # 架构使用指南

构建和测试

# 安装依赖
npm install

# 运行基本测试
npm test

# 运行全面测试
npm run test-full

# 启动开发服务器
npm run dev

# 生产环境构建
npm run build

开发特性

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

📄 许可证

MIT License - 详情请参阅 LICENSE 文件

🤝 贡献

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

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

贡献领域

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

🔗 相关链接

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

📞 支持

获取帮助

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

版本兼容性

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

💡 使用场景

1. 开发环境

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

2. 测试环境

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

3. 生产环境

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

4. AI 助手集成

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

🔐 安全最佳实践

权限配置建议

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

网络安全

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

审计和监控

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

MSSQL Server MCP 服务器

🚀 核心功能特性

主要能力

高级特性

📦 安装

NPM 安装

全局安装（推荐）

本地安装

手动安装

⚙️ 配置

环境变量

数据库连接设置

权限控制设置

日志配置

安全配置示例

开发环境（高权限）

测试环境（中等权限）

生产环境（限制权限）

🚀 使用方法

启动服务器

方式 1: CLI 启动

方式 2: 直接运行服务器

方式 3: 托管模式启动

方式 4: 开发模式启动（带调试）

完整环境设置示例

🛠️ 可用工具

1. sql_query

2. get_database_info

3. get_operation_logs

4. check_permissions

📊 日志记录和监控

日志分类

1. 请求/响应日志

2. SQL 操作日志

3. 连接池日志

4. 系统事件日志

日志文件位置

日志格式

🔒 安全特性

权限控制

SQL 注入防护

连接安全

🎯 编辑器集成

Cursor 编辑器配置

VS Code 配置

直接使用 MCP 服务器

🔧 连接池管理

自动特性

配置选项

🚨 故障排除

常见问题

1. 连接失败

2. 权限错误

3. 日志问题

调试模式

🏗️ 开发

项目结构

构建和测试

开发特性

📄 许可证

🤝 贡献

贡献领域

🔗 相关链接

📞 支持

获取帮助

版本兼容性

💡 使用场景

1. 开发环境

2. 测试环境

3. 生产环境

4. AI 助手集成

🔐 安全最佳实践

权限配置建议

网络安全