AI导哈

SQL数据库查询服务

MSSQL MCP Server是一个提供安全、只读访问Microsoft SQL Server数据库的模型上下文协议服务器，支持数据库模式发现、安全查询执行和商业智能分析。

  • by harshad-webx
  • JavaScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 harshad-webx/mssql-mcp-server

使用说明

MSSQL MCP服务器

一个全面的模型上下文协议（MCP）服务器，提供对Microsoft SQL server数据库的安全、只读访问。该服务器使AI助手能够发现数据库模式，安全执行查询，并通过标准化的界面生成商业智能见解。

🌟 特性

🔍 架构发现

  • 自动发现表、视图、列和关系
  • 详细的元数据，包括数据类型、约束和索引
  • 外键关系映射和依赖性分析
  • 支持多种数据库模式

🛡️ 安全第一

  • 只读执行 -阻止所有DML/DDL操作（INSERT、UPDATE、DELETE、DROP等）
  • SQL注入预防 -全面的查询验证和清理
  • 资源保护 -可配置的行限制和查询超时
  • 访问控制 -基于环境的数据库凭据管理

📊 强大的查询工具

  • 执行带有自动安全限制的SELECT查询
  • 查询性能分析和执行计划生成
  • 表搜索和过滤功能
  • 查询优化建议

🎯 商业智能

  • 常见数据分析场景的预构建提示
  • 特定领域的BI查询生成器（销售、财务、运营、客户分析）
  • 数据质量评估模板
  • 性能分析工作流程

🚀 快速开始

安装

选项1：从npm安装（推荐）

# Global installation
npm install -g @harshad-webx/mssql-mcp-server

# Or use without installing
npx @harshad-webx/mssql-mcp-server

选项2：从源代码安装

先决条件

  • Node.js 18+ - 点击此处下载
  • TypeScript -自动安装，带有依赖关系
  • Microsoft SQL Server -启用TCP/IP的任何版本
  • 数据库访问 -具有SELECT权限的用户帐户
# Clone the repository
git clone https://github.com/harshad-webx/mssql-mcp-server.git
cd mssql-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

2.配置

创建一个 .env 项目根目录中的文件：

# Copy the example environment file
cp .env.example .env

编辑 .env 使用您的数据库详细信息：

# MSSQL Database Configuration
DB_SERVER=your-sql-server.com
DB_DATABASE=YourDatabaseName
DB_USERNAME=your_username
DB_PASSWORD=your_secure_password
DB_PORT=1433
DB_ENCRYPT=true
DB_TRUST_SERVER_CERTIFICATE=false

3.测试连接

# Start the server to test
npm start

您应该看到： MSSQL MCP Server running on stdio

🔧 MCP客户端集成

Claude桌面集成

添加到您的Claude Desktop MCP配置(%APPDATA%\Claude\claude_desktop_config.json 在Windows或 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

选项1：使用npm全局安装（推荐）

{
  "mcpServers": {
    "mssql": {
      "command": "mssql-mcp-server",
      "env": {
        "DB_SERVER": "your-server.com",
        "DB_DATABASE": "YourDatabase",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_PORT": "1433",
        "DB_ENCRYPT": "true"
      }
    }
  }
}

选项2：使用npx（无需安装）

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["@harshad-webx/mssql-mcp-server"],
      "env": {
        "DB_SERVER": "your-server.com",
        "DB_DATABASE": "YourDatabase",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_PORT": "1433",
        "DB_ENCRYPT": "true"
      }
    }
  }
}

选项3：使用源代码安装

{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["C:/path/to/mssql-mcp-server/build/index.js"],
      "env": {
        "DB_SERVER": "your-server.com",
        "DB_DATABASE": "YourDatabase",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_PORT": "1433",
        "DB_ENCRYPT": "true"
      }
    }
  }
}

其他MCP客户端

对于其他MCP兼容客户端，请使用stdio传输：

node build/index.js

🛠️ 可用工具

1. execute_query

对数据库执行只读SQL SELECT查询。

参数：

  • query （字符串，必填）：要执行的SQL SELECT查询
  • maxRows （数字，可选）：返回的最大行数（默认值：100，最大值：1000）
  • includeExecutionPlan （布尔值，可选）：包括查询执行计划（默认值：false）

例子：

SELECT TOP 10 
    CustomerID, 
    CustomerName, 
    Country,
    YEAR(OrderDate) as OrderYear
FROM Customers c
INNER JOIN Orders o ON c.CustomerID = o.CustomerID
WHERE Country = 'USA'
ORDER BY OrderDate DESC

2. get_table_schema

获取特定表的全面架构信息。

参数：

  • schema （字符串，必填）：数据库架构名称（例如“dbo”）
  • table （字符串，必填）：表名

退货：

  • 表元数据（名称、类型、行数）
  • 列详细信息（数据类型、约束、描述）
  • 索引信息
  • 外键关系

3. search_tables

按名称模式搜索表和视图。

参数：

  • searchTerm （字符串，必填）：搜索模式以匹配表/视图名称

例子： 搜索所有包含“customer”的表

4. analyze_query

分析SQL查询性能并获得优化建议。

参数：

  • query （字符串，必填）：要分析的SQL查询

退货：

  • 执行统计信息
  • 查询执行计划
  • 业绩建议
  • 优化建议

🎯 可用提示

1. analyze_table_relationships

生成数据库表关系和外键约束的全面分析。

论据：

  • schema （可选）：要分析的特定模式

输出示例：

  • 外键关系映射
  • 依赖层次结构
  • 孤立表标识
  • 关系强度分析

2. find_data_quality_issues

生成SQL查询以识别常见的数据质量问题。

论据：

  • table （可选）：要检查的特定表（格式：schema.table）

检查包括：

  • 按列进行NULL值分析
  • 重复记录检测
  • 违反参考完整性
  • 数据格式不一致
  • 异常值识别

3. performance_analysis

生成查询以进行全面的数据库性能分析。

论据：

  • focus （可选）：焦点区域-“索引”、“查询”或“表”

分析领域：

  • 缺少索引建议
  • 未使用的索引标识
  • 昂贵的查询检测
  • 表统计回顾
  • 等待统计分析

4. business_intelligence_starter

为业务分析生成特定于域的BI查询。

论据：

  • domain （可选）：业务领域-“销售”、“财务”、“运营”或“客户”

查询类别：

  • 时间序列趋势分析
  • 同期对比分析
  • 客户细分
  • 绩效关键绩效指标
  • 收入分析

📋 使用示例

基本查询执行

// Through MCP client
{
  "tool": "execute_query",
  "arguments": {
    "query": "SELECT COUNT(*) as total_customers FROM Customers WHERE Country = 'USA'",
    "maxRows": 1
  }
}

架构发现

// Get detailed table information
{
  "tool": "get_table_schema",
  "arguments": {
    "schema": "dbo",
    "table": "Customers"
  }
}

数据质量分析

// Using prompt for data quality assessment
{
  "prompt": "find_data_quality_issues",
  "arguments": {
    "table": "Sales.Orders"
  }
}

🔒 安全功能

查询验证

  • 关键词过滤：块INSERT、UPDATE、DELETE、DROP、CREATE、ALTER、EXEC等。
  • 报表分析：只允许SELECT和WITH（CTE）语句
  • 评论监控：记录带有注释的查询以供安全审查

资源保护

  • 行限制：用于无界查询的自动TOP子句注入
  • 超时控制：可配置的查询超时（默认值：30秒）
  • 连接池：高效的数据库连接管理

访问控制

  • 环境变量：安全的凭据管理
  • 最低权限：专为只读数据库用户设计
  • 连接加密：对安全连接的TLS/SSL支持

🏗️ 数据库设置

推荐的数据库用户设置

-- Create a dedicated read-only user
CREATE LOGIN mcp_reader WITH PASSWORD = 'SecurePassword123!';
USE YourDatabase;
CREATE USER mcp_reader FOR LOGIN mcp_reader;

-- Grant minimal required permissions
GRANT SELECT ON SCHEMA::dbo TO mcp_reader;
GRANT VIEW DEFINITION ON SCHEMA::dbo TO mcp_reader;

-- Grant access to system views for schema discovery
GRANT VIEW ANY DEFINITION TO mcp_reader;

-- Optional: Grant access to specific schemas only
GRANT SELECT ON SCHEMA::Sales TO mcp_reader;
GRANT SELECT ON SCHEMA::Marketing TO mcp_reader;

网络配置

确保SQL Server配置为接受TCP/IP连接：

  1. 配置管理器 → SQL Server网络配置
  2. 启用TCP/IP协议
  3. 配置防火墙 允许端口1433（或您的自定义端口）
  4. 重新启动SQL Server服务

🐳 Docker支持

构建Docker镜像

docker build -t mssql-mcp-server .

使用Docker运行

docker run -e DB_SERVER=your-server \
           -e DB_DATABASE=YourDB \
           -e DB_USERNAME=user \
           -e DB_PASSWORD=pass \
           mssql-mcp-server

Docker Compose

version: '3.8'
services:
  mcp-server:
    build: .
    environment:
      - DB_SERVER=sql-server
      - DB_DATABASE=MyDatabase
      - DB_USERNAME=mcp_reader
      - DB_PASSWORD=securepassword
    depends_on:
      - sql-server

🔧 发展

可用脚本

# Development with auto-reload
npm run dev

# Build TypeScript
npm run build

# Watch mode for development
npm run watch

# Start production server
npm start

项目结构

src/
├── database/
│   ├── config.ts          # Database connection management
│   ├── schema.ts          # Schema discovery utilities
│   └── queryExecutor.ts   # Query execution and validation
└── index.ts               # Main MCP server implementation

添加新功能

  1. 新工具：添加到 ListToolsRequestSchema 和 CallToolRequestSchema 处理器
  2. 新提示：添加到 ListPromptsRequestSchema 和 GetPromptRequestSchema 处理器
  3. 安全规则：扩展 QueryExecutor.validateReadOnlyQuery() 方法

🐛 故障排除

常见问题

连接被拒绝

Error: connect ECONNREFUSED
  • 验证SQL Server是否正在运行且可访问
  • 检查防火墙设置和端口配置
  • 确保TCP/IP协议已启用

认证失败

Error: Login failed for user
  • 在中验证用户名和密码 .env
  • 确保用户具有所需的数据库权限
  • 检查SQL Server是否使用Windows身份验证与SQL身份验证

查询超时

Error: Query execution failed: Timeout
  • 优化查询性能
  • 增加超时时间 queryExecutor.ts
  • 检查是否阻止对数据库的查询 权限不足
Error: The SELECT permission was denied
  • 向数据库用户授予SELECT权限
  • 验证架构访问权限
  • 检查元数据查询的查看定义权限

调试模式

通过设置环境变量启用详细日志记录：

DEBUG=mcp:* npm start

📊 性能优化

查询优化提示

  1. 使用特定列：避免 SELECT * 为了获得更好的性能
  2. 添加WHERE子句：始终过滤数据以减少结果集
  3. 利用索引：确保对频繁查询的列进行索引
  4. 限制结果：使用TOP子句或maxRows参数

数据库优化

  1. 更新统计：保持表统计信息的最新状态
  2. 重建索引：保持指数健康
  3. 监测性能：使用内置分析工具
  4. 优化查询：定期审查执行计划

🤝 贡献

我们欢迎捐款！请参阅我们的投稿指南：

入门指南

  1. 分叉存储库
  2. 创建要素分支： git checkout -b feature/amazing-feature
  3. 通过适当的测试进行更改
  4. 提交您的更改： git commit -m 'Add amazing feature'
  5. 推到分支： git push origin feature/amazing-feature
  6. 打开拉取请求

开发指南

  • 遵循TypeScript的最佳实践
  • 添加新功能的测试
  • 更新变更文档
  • 确保维护安全验证

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🆘 支持

🙏 致谢

准备好用AI探索你的数据库了吗？现在就开始吧！ 🚀

相关 MCP