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

MSSQL Server MCP 服务器是一款基于Model Context Protocol(MCP)的企业级数据库管理工具，提供完整SQL支持与高级安全特性。核心功能包括细粒度权限控制（通过环境变量管理DDL/DROP/DELETE操作）、智能连接池优化、全面的操作日志记录（请求/SQL/连接池/系统日志）以及SQL注入防护。支持NPM安装或源码部署，可配置不同安全级别的环境（开发/测试/生产

qq_42945182

864人浏览 · 2025-08-15 18:30:05

qq_42945182 · 2025-08-15 18:30:05 发布

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 加密连接
定期更新数据库用户密码
监控异常访问模式

审计和监控

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

MCP Server for MSSQL Server

A comprehensive Model Context Protocol (MCP) server for MSSQL Server with advanced DDL support, granular permission control, comprehensive operation logging, and enterprise-grade connection management.

🚀 Key Features

Core Capabilities

Full SQL Support: Complete DDL and DML operation support with SQL injection protection
Advanced Permission Control: Granular control over DDL, DROP, DELETE operations via environment variables
Comprehensive Logging: Complete request/response logging, SQL operation tracking, and connection pool monitoring
Enterprise Connection Management: Automatic connection pool creation, health monitoring, and failover recovery
MCP Protocol Compliance: Full Model Context Protocol implementation with tool discovery and execution
Multi-Editor Support: Seamless integration with Cursor, VS Code, and other MCP-compatible editors

Advanced Features

Schema Auto-Prefixing: Automatic schema handling for multi-tenant environments
Connection Pool Optimization: Intelligent connection reuse and performance tuning
Error Handling: Comprehensive error logging and graceful failure recovery
Security Features: SQL injection prevention, parameterized query support, and operation validation

📦 Installation

NPM Installation

Global Installation (Recommended)

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

Local Installation

npm install @liangshanli/mcp-server-mssqlserver

Manual Installation

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

⚙️ Configuration

Environment Variables

Database Connection Settings

Environment Variable	Default	Description	Required
`MSSQL_SERVER`	`localhost`	MSSQL Server host address	✅
`MSSQL_PORT`	`1433`	MSSQL Server port number	✅
`MSSQL_USER`	`sa`	Database username	✅
`MSSQL_PASSWORD`	``	Database password	✅
`MSSQL_DATABASE`	``	Target database name	✅
`MSSQL_SCHEMA`	`dbo`	Default schema name	✅
`MSSQL_ENCRYPT`	`false`	Enable encryption	❌
`MSSQL_TRUST_SERVER_CERTIFICATE`	`true`	Trust server certificate	❌

Permission Control Settings

Environment Variable	Default	Description	Security Level
`ALLOW_DDL`	`false`	Allow CREATE, ALTER, DROP operations	🔴 High Risk
`ALLOW_DROP`	`false`	Allow DROP TABLE operations	🔴 High Risk
`ALLOW_DELETE`	`false`	Allow DELETE operations	🟡 Medium Risk

Logging Configuration

Environment Variable	Default	Description
`MCP_LOG_DIR`	`./logs`	Log directory path
`MCP_LOG_FILE`	`mcp-mssqlserver.log`	Log filename

Security Configuration Examples

Development Environment (High Permissions)

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

Testing Environment (Medium Permissions)

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

Production Environment (Restricted Permissions)

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

🚀 Usage

Starting the Server

Method 1: CLI Startup

npm start

Method 2: Direct Server Execution

npm run server

Method 3: Managed Mode

npm run start-managed

Method 4: Development Mode (with debugging)

npm run dev

Complete Environment Setup Example

# Database Connection
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

# Security Permissions
export ALLOW_DDL=true
export ALLOW_DROP=false
export ALLOW_DELETE=true

# Logging Configuration
export MCP_LOG_DIR=/var/log/mcp
export MCP_LOG_FILE=mssqlserver.log

# Start Server
npm start

🛠️ Available Tools

1. sql_query

Execute SQL queries with full DDL and DML support.

Parameters:

sql (string, required): SQL statement to execute

Features:

Automatic schema prefixing
Permission validation
Comprehensive error handling
SQL injection protection

Example:

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

Supported Operations:

✅ SELECT queries
✅ INSERT operations
✅ UPDATE operations
✅ DELETE operations (if permitted)
✅ CREATE TABLE (if DDL permitted)
✅ ALTER TABLE (if DDL permitted)
✅ DROP TABLE (if DROP permitted)

2. get_database_info

Retrieve comprehensive database information and configuration details.

Parameters: None

Returns:

Database list
Table list for current database
Current configuration
Permission status
Connection information

Example:

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

3. get_operation_logs

Access detailed operation logs for monitoring and debugging.

Parameters:

limit (number, optional): Number of log entries to return (default: 50)
offset (number, optional): Starting position for pagination (default: 0)

Log Information:

Request/response details
SQL execution results
Error messages and stack traces
Connection pool status
Performance metrics

Example:

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

4. check_permissions

Verify current permission configuration and access rights.

Parameters: None

Returns:

Current permission settings
Environment variable status
Configuration validation
Security recommendations

Example:

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

📊 Logging and Monitoring

Log Categories

1. Request/Response Logs

All MCP method calls
Parameter validation
Response generation
Error handling

2. SQL Operation Logs

SQL statement execution
Query results
Performance metrics
Error details

3. Connection Pool Logs

Pool creation/destruction
Health check results
Connection failures
Recovery attempts

4. System Event Logs

Server startup/shutdown
Configuration changes
Permission updates
Security events

Log File Location

Default: ./logs/mcp-mssqlserver.log
Customizable: Via MCP_LOG_DIR and MCP_LOG_FILE environment variables

Log Format

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

🔒 Security Features

Permission Control

Granular Access Control: Fine-grained permission management for different operation types
Environment-Based Security: Secure configuration through environment variables
Operation Validation: Real-time permission checking before SQL execution
Audit Logging: Complete audit trail of all operations

SQL Injection Protection

Parameterized Queries: Support for prepared statements
Input Validation: Comprehensive input sanitization
Error Masking: Secure error message handling
Query Logging: Complete SQL operation tracking

Connection Security

Encrypted Connections: Support for SSL/TLS encryption
Certificate Validation: Configurable certificate trust settings
Connection Pooling: Secure connection management
Timeout Protection: Configurable connection and request timeouts

🎯 Editor Integration

Cursor Editor Configuration

Create .cursor/mcp.json in your project root:

{
  "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 Configuration

Install VS Code MCP extension
Create .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"
      }
    }
  }
}

Direct MCP Server Usage

Server communicates via stdin/stdout with MCP clients:

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

🔧 Connection Pool Management

Automatic Features

Auto-Creation: Connection pool automatically created on notifications/initialized
Health Monitoring: 5-minute interval health checks
Auto-Recovery: Automatic pool recreation on failure
Performance Optimization: Intelligent connection reuse
Graceful Shutdown: Proper connection cleanup on server termination

Configuration Options

Pool Size: Configurable minimum and maximum connections
Timeout Settings: Customizable connection and request timeouts
Retry Logic: Configurable retry attempts for failed connections
Load Balancing: Intelligent connection distribution

🚨 Troubleshooting

Common Issues

1. Connection Failures

Symptoms:

“Connection refused” errors
Timeout errors
Authentication failures

Solutions:

Verify MSSQL Server is running
Check firewall settings
Validate connection parameters
Confirm network connectivity

2. Permission Errors

Symptoms:

“Operation not allowed” errors
“Access denied” messages
Permission validation failures

Solutions:

Check environment variable configuration
Verify database user permissions
Confirm ALLOW_* settings
Review security configuration

3. Logging Issues

Symptoms:

Missing log files
Incomplete log entries
Permission denied errors

Solutions:

Check log directory permissions
Verify disk space availability
Confirm log file path validity
Review file system permissions

Debug Mode

Enable detailed debugging information:

npm run dev

Debug Information:

Detailed SQL execution logs
Connection pool status
Permission validation details
Error stack traces
Performance metrics

🏗️ Development

Project Structure

mcp-server-mssqlserver/
├── bin/
│   └── cli.js              # CLI startup script
├── src/
│   └── server-final.js     # Main server implementation
├── start-server.js         # Managed startup script
├── package.json            # Project configuration
├── README.md              # English documentation
├── README.zh-CN.md        # Chinese documentation
└── SCHEMA_USAGE.md        # Schema usage guide

Building and Testing

# Install dependencies
npm install

# Run basic tests
npm test

# Run comprehensive tests
npm run test-full

# Start development server
npm run dev

# Build for production
npm run build