MCP Ocp Test

MS SQL MCP服务器1.1

一个易于使用的桥梁，让像Claude这样的人工智能助手可以直接查询和探索Microsoft SQL Server数据库。无需编码经验！

这个工具做什么？

该工具允许AI助手：

1. 发现 SQL Server数据库中的表
2. 视图 表结构（列、数据类型等）
3. 执行 安全的只读SQL查询
4. 生成 来自自然语言请求的SQL查询

🌟 为什么你需要这个工具

弥合数据和人工智能之间的差距

• 无需编码：让Claude和其他AI助手直接访问您的SQL Server数据库，而无需编写复杂的集成代码
• 保持控制：默认情况下，所有查询都是只读的，确保您的数据保持安全
• 私密且安全：您的数据库凭据将保留在本地，永远不会发送到外部服务

实际效益

• 节省人工工时：不再复制粘贴数据或查询结果与AI共享
• 更深入的分析：AI可以导航整个数据库模式，并跨多个表提供见解
• 自然语言接口：用简单的英语询问有关数据的问题
• 结束上下文限制问题：访问超出正常AI上下文窗口的大型数据集

非常适合

• 数据分析师 谁希望AI在不共享凭据的情况下帮助解释SQL数据
• 开发者 寻找一种通过自然对话快速探索数据库结构的方法
• 业务分析师 需要洞察力而不需要SQL专业知识的人
• 数据库管理员 谁想提供对人工智能工具的受控访问

🚀 快速入门指南

步骤1：安装先决条件

• 安装 （版本14或更高）
• 可以访问Microsoft SQL Server数据库（本地或Azure）

步骤2：克隆和设置

# Clone this repository
git clone https://github.com/dperussina/mssql-mcp-server.git

# Navigate to the project directory
cd mssql-mcp-server

# Install dependencies
npm install

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

步骤3：配置数据库连接

编辑 .env 包含数据库凭据的文件：

DB_USER=your_username
DB_PASSWORD=your_password
DB_SERVER=your_server_name_or_ip
DB_DATABASE=your_database_name
PORT=3333
HOST=0.0.0.0                    # Host for the server to listen on, e.g., 'localhost' or '0.0.0.0'
TRANSPORT=stdio
SERVER_URL=http://localhost:3333
DEBUG=false                     # Set to 'true' for detailed logging (helpful for troubleshooting)
QUERY_RESULTS_PATH=/path/to/query_results  # Directory where query results will be saved as JSON files

步骤4：启动服务器

# Start with default stdio transport
npm start

# OR start with HTTP/SSE transport for network access
npm run start:sse

第五步：试试看！

# Run the interactive client
npm run client

📊 示例用例

1. 无需编写SQL即可探索数据库结构

   mcp_SQL_mcp_discover_database()

1. 获取特定表格的详细信息

   mcp_SQL_mcp_table_details({ tableName: "Customers" })

1. 运行安全查询

   mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Customers", returnResults: true })

1. 按名称模式查找表

   mcp_SQL_mcp_discover_tables({ namePattern: "%user%" })

1. 使用分页来导航大型结果集

   // First page
   mcp_SQL_mcp_execute_query({ 
     sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY", 
     returnResults: true 
   })

   // Next page
   mcp_SQL_mcp_execute_query({ 
     sql: "SELECT * FROM Users ORDER BY Username OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY", 
     returnResults: true 
   })

1. 基于光标的分页可实现最佳性能

   // First page
   mcp_SQL_mcp_execute_query({ 
     sql: "SELECT TOP 10 * FROM Users ORDER BY Username", 
     returnResults: true 
   })

   // Next page using the last value as cursor
   mcp_SQL_mcp_execute_query({ 
     sql: "SELECT TOP 10 * FROM Users WHERE Username > 'last_username' ORDER BY Username", 
     returnResults: true 
   })

1. 问自然语言问题

   "Show me the top 5 customers with the most orders in the last month"

💡 实际应用

商业智能

• 销售业绩分析：“向我展示过去一年的月度销售趋势，并按地区确定我们表现最佳的产品。”
• 客户细分：“按购买频率、平均订单价值和地理位置分析我们的客户群。”
• 财务报告：“创建一份季度损益报告，将今年与去年进行比较。”

用于数据库管理

• 模式优化：“通过检查查询性能数据，帮助我识别缺少索引的表。”
• 数据质量审计：“查找所有信息不完整或值无效的客户记录。”
• 使用分析：“显示哪些表访问最频繁，哪些查询资源最密集。”

为了发展

• API勘探：“我正在构建一个API-帮助我分析数据库模式以设计适当的端点。”
• 查询优化：“查看此复杂的查询并提出性能改进建议。”
• 数据库文档：“为我们的数据库结构创建全面的文档，并解释关系。”

🖥️ 交互式客户端功能

捆绑的客户端提供了一个简单的菜单驱动界面：

1. 列出可用资源 -查看可用信息
2. 列出可用工具 -查看您可以执行哪些操作
3. 执行SQL查询 -运行只读SQL查询
4. 获取表格详细信息 -查看任何表的结构
5. 读取数据库架构 -查看所有表及其关系
6. 生成SQL查询 -将自然语言转换为SQL

🧠 有效提示和工具使用指南

当通过此MCP服务器与Claude或其他AI助手合作时，您表达请求的方式会显著影响结果。以下是如何帮助人工智能有效地使用数据库工具：

基本工具调用格式

当提示AI使用此工具时，请遵循以下结构：

Can you use the SQL MCP tools to [your goal]?

For example:
- Check what tables exist in my database
- Query the Customers table and show me the first 10 records
- Find all orders from the past month

基本命令和语法

以下是主要工具及其正确语法：

// Discover the database structure
mcp_SQL_mcp_discover_database()

// Get detailed information about a specific table
mcp_SQL_mcp_table_details({ tableName: "YourTableName" })

// Execute a query and return results
mcp_SQL_mcp_execute_query({ 
  sql: "SELECT * FROM YourTable WHERE Condition", 
  returnResults: true 
})

// Find tables by name pattern
mcp_SQL_mcp_discover_tables({ namePattern: "%pattern%" })

// Access saved query results (for large result sets)
mcp_SQL_mcp_get_query_results({ uuid: "provided-uuid-here" })

何时使用每种工具：

• 数据库发现：当AI不熟悉您的数据库结构时，请从这里开始。
• 表详细信息：在编写查询之前专注于特定表时使用。
• 查询执行：当您需要检索或分析实际数据时。
• 按模式查找表：查找与特定域相关的表时。

有效的激励模式

分步工作流

对于复杂的任务，引导AI完成一系列步骤：

I'd like to analyze our sales data. Please:
1. First use mcp_SQL_mcp_discover_tables to find tables related to sales
2. Use mcp_SQL_mcp_table_details to examine the structure of relevant tables
3. Create a query with mcp_SQL_mcp_execute_query that shows monthly sales by product category

先结构，后查询

First, discover what tables exist in my database. Then, look at the structure
of the Customers table. Finally, show me the top 10 customers by total purchase amount.

要求解释

Query the top 5 underperforming products based on sales vs. forecasts,
and explain your approach to writing this query.

SQL Server方言注释

提醒AI SQL Server的具体语法：

Please use SQL Server syntax for pagination:
- For offset/fetch: "OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY"
- For cursor-based: "WHERE ID > last_id ORDER BY ID"

纠正工具使用

如果AI使用了不正确的语法，您可以帮助它：

That's not quite right. Please use this format for the tool call:
mcp_SQL_mcp_execute_query({ 
  sql: "SELECT * FROM Customers WHERE Region = 'West'",
  returnResults: true
})

通过提示进行故障排除

如果人工智能正在努力完成数据库任务，请尝试以下方法：

1. 更具体地了解表格： 在编写该查询之前，请检查CustomerOrders表是否存在以及它有哪些列

1. 将复杂任务分解为步骤： “让我们一步一步地处理这个问题。首先，查看Products表结构。然后，检查Orders表…”

1. 询问中间结果： “首先对该表运行一个简单的查询，这样我们就可以在尝试更复杂的分析之前验证数据格式。”

1. 请求查询说明： “写完这个查询后，解释每个部分的作用，这样我就可以验证它是否在做我需要的事情。”

🔎 高级查询功能

表发现和勘探

MCP服务器为探索数据库结构提供了强大的工具：

• 基于模式的表发现：查找与特定模式匹配的表

  mcp_SQL_mcp_discover_tables({ namePattern: "%order%" })

• 架构概述：按模式获取表的高级视图

  mcp_SQL_mcp_execute_query({ 
    sql: "SELECT TABLE_SCHEMA, COUNT(*) AS TableCount FROM INFORMATION_SCHEMA.TABLES GROUP BY TABLE_SCHEMA" 
  })

• 栏目探索：检查任何表的列元数据

  mcp_SQL_mcp_table_details({ tableName: "dbo.Users" })

分页技术

服务器支持多种分页方法来处理大型数据集：

1. 偏移/提取分页：使用OFFSET和FETCH进行标准SQL分页

   mcp_SQL_mcp_execute_query({ 
     sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY" 
   })

1. 基于光标的分页：对大型数据集更有效

   // Get first page
   mcp_SQL_mcp_execute_query({ 
     sql: "SELECT TOP 10 * FROM Users ORDER BY Username" 
   })

   // Get next page using last value as cursor
   mcp_SQL_mcp_execute_query({ 
     sql: "SELECT TOP 10 * FROM Users WHERE Username > 'last_username' ORDER BY Username" 
   })

1. 用数据计数：检索总计数和分页数据

   mcp_SQL_mcp_execute_query({ 
     sql: "WITH TotalCount AS (SELECT COUNT(*) AS Total FROM Users) SELECT TOP 10 u.*, t.Total FROM Users u CROSS JOIN TotalCount t ORDER BY Username" 
   })

复杂的连接和关系

探索具有联接操作的表之间的关系：

mcp_SQL_mcp_execute_query({ 
  sql: "SELECT u.Username, u.Email, r.RoleName FROM Users u JOIN UserRoles ur ON u.Username = ur.Username JOIN Roles r ON ur.RoleId = r.RoleId ORDER BY u.Username"
})

分析查询

运行聚合和分析查询以获得见解：

mcp_SQL_mcp_execute_query({ 
  sql: "SELECT UserType, COUNT(*) AS UserCount, SUM(CASE WHEN IsActive = 1 THEN 1 ELSE 0 END) AS ActiveUsers FROM Users GROUP BY UserType"
})

使用SQL Server功能

MCP服务器支持SQL server特定功能：

• 通用表表达式（CTE）
• 窗口功能
• JSON操作
• 层次查询
• 全文搜索 （在数据库中配置时）

🔗 集成选项

Claude桌面集成

只需几个简单的步骤，即可将此工具直接连接到Claude Desktop：

1. 从以下位置安装Claude Desktop anthropic.com
2. 编辑Claude的配置文件：

- 地点： ~/Library/Application Support/Claude/claude_desktop_config.json - 添加此配置：

{
    "mcpServers": {
        "mssql": {
            "command": "node",
            "args": [
                "/FULL/PATH/TO/mssql-mcp-server/server.mjs"
            ]
        }
    }
}

1. 替换 /FULL/PATH/TO/ 带有克隆此存储库的实际路径
2. 重新启动克劳德桌面
3. 在Claude Desktop中查找工具图标-您现在可以直接使用数据库命令！

与Cursor IDE连接

Cursor是一个AI驱动的代码编辑器，可以利用此工具进行高级数据库交互。以下是如何设置它：

在游标中设置

1. 打开Cursor IDE（从下载 cursor.sh 如果你没有）
2. 使用HTTP/SSE传输启动MS SQL MCP服务器：

   npm run start:sse

1. 在Cursor中创建新工作区或打开现有项目
2. 输入光标设置
3. 点击MCP
4. 添加新的MCP服务器
5. 命名您的MCP服务器，选择类型：sse
6. 输入服务器URL：localhost:3333/sse（或您运行它的端口）

在游标中使用数据库命令

连接后，您可以直接在Cursor的AI聊天中使用MCP命令：

1. 让Cursor中的Claude浏览您的数据库：

   Can you show me the tables in my database?

1. 执行特定查询：

   Query the top 10 records from the Customers table

1. 生成并运行复杂的查询：

   Find all orders from the last month with a value over $1000

光标连接故障排除

• 确保MS SQL MCP服务器正在使用HTTP/SSE传输运行
• 检查端口是否正确，是否与.env文件中的端口匹配
• 确保防火墙没有阻止连接
• 如果使用不同的IP/主机名，请更新.env文件中的SERVER_URL

🔄 交通方式详解

选项1:stdio传输（默认）

最适合：直接与Claude Desktop或捆绑客户端一起使用

npm start

选项2:HTTP/SSE传输

最适合：网络访问或与web应用程序一起使用

npm run start:sse

🛡️ 安全功能

• 默认情况下为只读：无数据修改风险
• 私人凭据：数据库连接详细信息保留在您的 .env 文件
• SQL注入保护：SQL查询的内置验证

🔎 新用户故障排除

“无法连接到数据库”

• 检查你的 .env 用于正确数据库凭据的文件
• 确保您的SQL Server正在运行并接受连接
• 对于Azure SQL，请验证防火墙设置中是否允许使用您的IP

“找不到模块”错误

• 跑 npm install 再次确保所有依赖项都已安装
• 确保你使用的是Node.js 14或更高版本

“传输错误”或“连接被拒绝”

• 对于HTTP/SSE传输，请验证.env中的PORT是否可用
• 确保没有防火墙阻止连接

Claude Desktop无法连接

• 仔细检查您的路径 claude_desktop_config.json
• 确保你使用的是绝对路径，而不是相对路径
• 更改后完全重新启动Claude Desktop

📚 了解SQL Server基础知识

如果您是SQL Server的新手，以下是一些关键概念：

• 表格：将数据存储在行和列中
• 模式：表的逻辑分组（如文件夹）
• 查询：检索或分析数据的命令
• 视图：保存预定义查询以便于访问

这个工具可以帮助你探索所有这些，而不需要成为SQL专家！

🏗️ 架构和核心模块

MS SQL MCP Server采用模块化架构构建，将可维护性和可扩展性问题分开：

核心模块

database.mjs -数据库连接

• 管理SQL Server连接池
• 提供具有重试逻辑和错误处理的查询执行
• 处理数据库连接、事务和配置
• 包括用于清除SQL和格式错误的实用程序

tools.mjs -工具注册

• 在MCP服务器上注册所有数据库工具
• 实施工具验证和参数检查
• 为SQL查询、表探索和数据库发现提供核心功能
• 映射工具调用数据库操作

resources.mjs -数据库资源

• 通过资源端点公开数据库元数据
• 提供架构信息、表列表和过程文档
• 为AI消费格式化数据库结构信息
• 包括用于数据库探索的发现实用程序

pagination.mjs -结果导航

• 为大型结果集实现基于光标的分页
• 提供用于生成下一页/上一页游标的实用程序
• 转换SQL查询以支持分页
• 处理SQL Server的OFFSET/FETCH分页语法

errors.mjs -错误处理

• 为不同的故障场景定义自定义错误类型
• 实现JSON-RPC错误格式化
• 提供人类可读的错误消息
• 包括用于全局错误处理的中间件

logger.mjs -测井系统

• 使用多种传输配置Winston日志记录
• 提供上下文感知请求日志记录
• 处理日志轮换和格式化
• 捕获未捕获的异常和未处理的拒绝

这些模块如何协同工作

1. 当收到工具调用时，MCP服务器会将其路由到中的相应处理程序 tools.mjs
2. 工具处理程序验证参数并构造数据库查询
3. 查询是通过中的函数执行的 database.mjs，可能从以下位置分页 pagination.mjs
4. 结果被格式化并返回给客户端
5. 任何错误都会被捕获并处理 errors.mjs
6. 所有操作均通过以下方式记录 logger.mjs

该架构确保：

• 清晰地分离关注点
• 一致的错误处理
• 综合录井
• 高效的数据库连接管理
• 可扩展的查询执行

⚙️ 环境配置说明

这 .env 文件控制MS SQL MCP Server如何连接到您的数据库并进行操作。以下是对每个设置的详细说明：

# Database Connection Settings
DB_USER=your_username           # SQL Server username
DB_PASSWORD=your_password       # SQL Server password
DB_SERVER=your_server_name_or_ip
DB_DATABASE=your_database_name

# Server Configuration
PORT=3333                       # Port for the HTTP/SSE server to listen on
HOST=0.0.0.0                    # Host for the server to listen on, e.g., 'localhost' or '0.0.0.0'
TRANSPORT=stdio                 # Connection method: 'stdio' (for Claude Desktop) or 'sse' (for network connections)
SERVER_URL=http://localhost:3333 # Base URL when using SSE transport. If HOST is '0.0.0.0', external clients use http://:${PORT}

# Advanced Settings
DEBUG=false                     # Set to 'true' for detailed logging (helpful for troubleshooting)
QUERY_RESULTS_PATH=/path/to/query_results  # Directory where query results will be saved as JSON files

连接类型说明

stdio运输

• 直接与Claude Desktop连接时使用
• 通信通过标准输入/输出流进行
• 集 TRANSPORT=stdio 在.env文件中
• 与一起跑步 npm start

HTTP/SSE传输

• 通过网络连接时使用（如使用Cursor IDE）
• 使用服务器发送事件（SSE）进行实时通信
• 集 TRANSPORT=sse 在.env文件中
• 配置 SERVER_URL 匹配您的服务器地址
• 与一起跑步 npm run start:sse

SQL Server连接示例

本地SQL Server

DB_USER=sa
DB_PASSWORD=YourStrongPassword
DB_SERVER=localhost
DB_DATABASE=AdventureWorks

Azure SQL数据库

DB_USER=azure_admin@myserver
DB_PASSWORD=YourStrongPassword
DB_SERVER=myserver.database.windows.net
DB_DATABASE=AdventureWorks

查询结果存储

查询结果保存为JSON文件，保存在由指定的目录中 QUERY_RESULTS_PATH这可以防止大型结果集压倒对话。你可以：

• 将此项留空以使用默认值 query-results 项目中的目录
• 设置自定义路径，如 /Users/username/Documents/query-results
• 使用工具响应中提供的UUID访问保存的结果

📝 许可证

国际协调委员会