Mcp Sqlserver

MCP SQL Server

一个只读的 Model Context Protocol（MCP）服务，适用于 Microsoft SQL Server，可让 AI Agent 安全地探索和查询 SQL Server 数据库。

快速开始

第 1 步：安装软件包

# Global installation (recommended)
npm install -g @bilims/mcp-sqlserver

# Verify installation
mcp-sqlserver --version

第 2 步：配置 SQL Server 连接

选择你的 SQL Server 类型，并按照相应说明进行配置：

Azure SQL Database

export SQLSERVER_HOST="your-server.database.windows.net"
export SQLSERVER_USER="your-username"
export SQLSERVER_PASSWORD="your-password"
export SQLSERVER_DATABASE="your-database"
export SQLSERVER_ENCRYPT="true"
export SQLSERVER_TRUST_CERT="false"

本地部署的 SQL Server

export SQLSERVER_HOST="your-sql-server.company.com"
export SQLSERVER_USER="your-username"
export SQLSERVER_PASSWORD="your-password"
export SQLSERVER_DATABASE="your-database"
export SQLSERVER_ENCRYPT="true"
export SQLSERVER_TRUST_CERT="true"  # For self-signed certificates

本地 SQL Server Express

export SQLSERVER_HOST="localhost\\SQLEXPRESS"
export SQLSERVER_USER="sa"
export SQLSERVER_PASSWORD="your-password"
export SQLSERVER_DATABASE="master"
export SQLSERVER_ENCRYPT="false"
export SQLSERVER_TRUST_CERT="true"

第 3 步：测试连接

# Test your configuration
mcp-sqlserver --help

# Quick connection test (press Ctrl+C to exit)
mcp-sqlserver

第 4 步：添加到 Claude Desktop

1. 找到 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

2. 添加 MCP 服务配置：

{
  "mcpServers": {
    "sqlserver": {
      "command": "mcp-sqlserver",
      "env": {
        "SQLSERVER_HOST": "your-server.database.windows.net",
        "SQLSERVER_USER": "your-username",
        "SQLSERVER_PASSWORD": "your-password",
        "SQLSERVER_DATABASE": "your-database",
        "SQLSERVER_ENCRYPT": "true",
        "SQLSERVER_TRUST_CERT": "false"
      }
    }
  }
}

3. 重启 Claude Desktop

第 5 步：开始探索！

在 Claude Desktop 中尝试以下命令：

• "测试 SQL Server 连接"
• "列出服务器上的所有数据库"
• "显示 [database name] 中的表"
• "描述 Users 表的结构"
• "显示外键关系"

功能特性

• 🔒 只读操作：仅允许 SELECT 查询，并进行全面的安全验证
• 🗄️ 架构发现：探索数据库、表、视图、关系和元数据
• 📊 数据探索：执行安全查询，并内置行数限制和超时设置
• 🔐 面向企业环境：通过证书信任建立加密连接，适用于生产环境
• 🛡️ 安全优先：查询验证、SQL 注入防护和访问控制

可用工具

架构发现

• list_databases - 列出 SQL Server 实例上的所有数据库
• list_tables - 列出数据库或架构中的表
• list_views - 列出数据库或架构中的视图
• describe_table - 获取详细的表架构，包括列、数据类型和约束

关系分析

• get_foreign_keys - 获取表的外键关系
• get_table_stats - 获取表统计信息，包括行数和大小信息

数据探索

• execute_query - 执行经过安全验证的只读 SELECT 查询
• get_server_info - 获取 SQL Server 版本、版本类型和配置信息

Claude Desktop 常用命令

配置好 MCP 服务后，可以尝试使用以下自然语言命令：

入门命令

"Test the SQL Server connection"
"Show me server information"
"List all databases on this server"
"What tables are in the [database name] database?"

数据库探索

"Describe the structure of the Users table"
"Show me foreign key relationships in this database"
"What are the largest tables by row count?"
"Give me a sample of data from the Orders table"

高级分析

"Help me understand the relationship between Orders and Customers"
"Show me all lookup tables in this database"
"What columns contain date/time information?"
"Find tables that might contain user authentication data"

自定义查询

"Run this query: SELECT TOP 10 * FROM Products WHERE Price > 100"
"Show me all customers created in the last 30 days"
"What are the different product categories in the database?"

安装

npm install
npm run build

配置

此服务使用环境变量进行配置：

必需项

• SQLSERVER_USER - SQL Server 用户名
• SQLSERVER_PASSWORD - SQL Server 密码

可选项

• SQLSERVER_HOST - 服务器主机名（默认值：localhost）
• SQLSERVER_DATABASE - 默认数据库名称
• SQLSERVER_PORT - 端口号（默认值：1433）
• SQLSERVER_ENCRYPT - 启用加密（默认值：true）
• SQLSERVER_TRUST_CERT - 信任服务器证书（默认值：true）
• SQLSERVER_CONNECTION_TIMEOUT - 连接超时时间，单位为毫秒（默认值：30000）
• SQLSERVER_REQUEST_TIMEOUT - 请求超时时间，单位为毫秒（默认值：60000）
• SQLSERVER_MAX_ROWS - 每个查询的最大行数（默认值：1000）

用法

环境变量

export SQLSERVER_HOST="your-server.database.windows.net"
export SQLSERVER_USER="your-username"
export SQLSERVER_PASSWORD="your-password"
export SQLSERVER_DATABASE="your-database"
export SQLSERVER_ENCRYPT="true"
export SQLSERVER_TRUST_CERT="true"

运行服务

npm start

安装选项

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

npm install -g @bilims/mcp-sqlserver

选项 2：本地安装

npm install @bilims/mcp-sqlserver
npx mcp-sqlserver

选项 3：通过 npx 运行（无需安装）

npx @bilims/mcp-sqlserver

集成示例

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "sqlserver": {
      "command": "mcp-sqlserver",
      "env": {
        "SQLSERVER_HOST": "your-server.database.windows.net",
        "SQLSERVER_USER": "your-username",
        "SQLSERVER_PASSWORD": "your-password",
        "SQLSERVER_DATABASE": "your-database"
      }
    }
  }
}

Claude Code CLI

# Set environment variables
export SQLSERVER_HOST="your-server"
export SQLSERVER_USER="your-username"
export SQLSERVER_PASSWORD="your-password"

# Use with Claude Code
claude mcp add sqlserver mcp-sqlserver

搭配 MCP Extension 使用 VSCode

为 VSCode 安装 MCP Extension，并添加服务配置。

安全功能

查询验证

• 仅允许 SELECT、WITH、SHOW、DESCRIBE 和 EXPLAIN 语句
• 全面禁止危险关键字（INSERT、UPDATE、DELETE、DROP 等）
• 检测 SQL 注入模式
• 自动清理查询

连接安全

• 默认启用 TLS/SSL 加密
• 为企业环境提供服务器证书信任选项
• 支持连接池和超时控制
• 可配置请求超时

结果限制

• 可配置每次查询的最大行数
• 自动为 SELECT 查询注入 TOP 子句
• 跟踪查询执行时间
• 内存使用保护

示例查询

连接后，你可以通过 MCP 客户端使用这些工具：

// List all databases
await callTool("list_databases", {});

// List tables in a specific schema
await callTool("list_tables", { schema: "dbo" });

// Get table schema details
await callTool("describe_table", { 
  table_name: "Users", 
  schema: "dbo" 
});

// Execute a read-only query
await callTool("execute_query", { 
  query: "SELECT TOP 10 * FROM Users WHERE active = 1",
  limit: 10
});

// Get foreign key relationships
await callTool("get_foreign_keys", { 
  table_name: "Orders" 
});

开发

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run linting
npm run lint

# Run tests
npm test

故障排除

连接问题

1. 验证服务器主机名和端口
2. 检查加密／证书设置是否与 SQL Server 配置匹配
3. 确保用户拥有适当的读取权限
4. 先使用 SQL Server Management Studio 测试连接

权限问题

用户帐户至少需要：

• 数据库的 CONNECT 权限
• 对要查询的表／视图拥有 SELECT 权限
• 访问系统视图以查询元数据

常见 SQL Server 配置

Azure SQL Database

export SQLSERVER_HOST="your-server.database.windows.net"
export SQLSERVER_ENCRYPT="true"
export SQLSERVER_TRUST_CERT="false"

使用自签名证书的本地 SQL Server

export SQLSERVER_HOST="sql-server.company.com"
export SQLSERVER_ENCRYPT="true" 
export SQLSERVER_TRUST_CERT="true"

许可证

MIT

参与贡献

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

支持

如有问题和疑问：

• 查看上方的故障排除部分
• 查阅 SQL Server 连接文档
• 确保 MCP 客户端兼容

---

基于 Model Context Protocol SDK 构建，实现无缝 AI 集成。