Mcpql

Mcpql

数据库 TypeScript

🚀 MCPQL - SQL Server MCP

MCPQL 是一款全面的 模型上下文协议（MCP） 服务器，专为 SQL Server 数据库操作而设计。该服务器通过 MCP 协议提供了 10 种强大的工具，可用于数据库分析、对象发现和数据操作。

🚀 快速开始

前提条件

  • Node.js 18 及以上版本和 npm
  • 具备适当连接凭证的 SQL Server 数据库
  • 兼容 MCP 的客户端（如 Claude Desktop、Cursor IDE 或任何 MCP 客户端）

安装与配置

选项 1：通过 GitHub 使用 npx（推荐）

无需安装！只需配置您的 MCP 客户端：

对于 Claude Desktop (claude_desktop_config.json)：

{
"mcpServers": {
"mcpql": {
"command": "npx",
"args": ["-y", "hendrickcastro/mcpql"],
"env": {
"DB_AUTHENTICATION_TYPE": "sql",
"DB_SERVER": "your_server",
"DB_NAME": "your_database",
"DB_USER": "your_username",
"DB_PASSWORD": "your_password",
"DB_PORT": "1433",
"DB_ENCRYPT": "false",
"DB_TRUST_SERVER_CERTIFICATE": "true"
}
}
}
}

对于 Cursor IDE：

{
"mcpServers": {
"mcpql": {
"command": "npx",
"args": ["-y", "hendrickcastro/mcpql"],
"env": {
"DB_AUTHENTICATION_TYPE": "sql",
"DB_SERVER": "your_server",
"DB_NAME": "your_database",
"DB_USER": "your_username",
"DB_PASSWORD": "your_password",
"DB_PORT": "1433",
"DB_ENCRYPT": "false",
"DB_TRUST_SERVER_CERTIFICATE": "true"
}
}
}
}

选项 2：本地开发安装

  1. 克隆并设置：
git clone https://github.com/hendrickcastro/MCPQL.git
cd MCPQL
npm install
npm run build
  1. 配置数据库连接： 创建一个 .env 文件，并填入您的数据库凭证：
# 基本 SQL Server 连接
DB_AUTHENTICATION_TYPE=sql
DB_SERVER=localhost
DB_NAME=MyDatabase
DB_USER=sa
DB_PASSWORD=YourPassword123!
DB_PORT=1433
DB_ENCRYPT=false
DB_TRUST_SERVER_CERTIFICATE=true
  1. 使用本地路径配置 MCP 客户端：
{
"mcpServers": {
"mcpql": {
"command": "node",
"args": ["path/to/MCPQL/dist/server.js"]
}
}
}

✨ 主要特性

MCPQL 为 SQL Server 数据库操作提供了 10 种全面的工具：

1. 🏗️ 表分析 - mcp_table_analysis

完成表结构分析，包括列、键、索引和约束。

2. 📋 存储过程分析 - mcp_sp_structure

分析存储过程结构，包括参数、依赖项和源代码。

3. 👀 数据预览 - mcp_preview_data

预览表数据，支持可选的过滤和行限制。

4. 📊 列统计信息 - mcp_get_column_stats

获取特定列的全面统计信息。

5. ⚙️ 执行存储过程 - mcp_execute_procedure

使用参数执行存储过程并返回结果。

6. 🔍 执行 SQL 查询 - mcp_execute_query

执行自定义 SQL 查询，并进行全面的错误处理。

7. ⚡ 快速数据分析 - mcp_quick_data_analysis

进行快速统计分析，包括行数统计、列分布和前几个值。

8. 🔎 全面搜索 - mcp_search_comprehensive

根据名称和定义在数据库对象中进行搜索，支持可配置的搜索条件。

9. 🔗 对象依赖关系 - mcp_get_dependencies

获取数据库对象（表、视图、存储过程等）的依赖关系。

10. 🎯 示例值 - mcp_get_sample_values

从表的特定列中获取示例值。

💻 使用示例

分析表

// 获取完整的表结构
const analysis = await mcp_table_analysis({
table_name: "dbo.Users"
});

// 获取快速数据概述
const overview = await mcp_quick_data_analysis({
table_name: "dbo.Users",
sample_size: 500
});

// 使用过滤器预览表数据
const data = await mcp_preview_data({
table_name: "dbo.Users",
filters: { "Status": "Active", "Department": "IT" },
limit: 25
});

查找数据库对象

// 查找所有包含 "User" 的对象
const objects = await mcp_search_comprehensive({
pattern: "User",
search_in_names: true,
search_in_definitions: false
});

// 查找查询特定表的存储过程
const procedures = await mcp_search_comprehensive({
pattern: "FROM Users",
object_types: ["PROCEDURE"],
search_in_definitions: true
});

分析存储过程

// 获取完整的存储过程分析
const spAnalysis = await mcp_sp_structure({
sp_name: "dbo.usp_GetUserData"
});

// 执行存储过程
const result = await mcp_execute_procedure({
sp_name: "dbo.usp_GetUserById",
params: { "UserId": 123, "IncludeDetails": true }
});

数据分析

// 获取列统计信息
const stats = await mcp_get_column_stats({
table_name: "dbo.Users",
column_name: "Age"
});

// 从列中获取示例值
const samples = await mcp_get_sample_values({
table_name: "dbo.Users",
column_name: "Department",
limit: 15
});

🔧 技术细节

环境变量与连接类型

MCPQL 支持多种 SQL Server 连接类型，并提供全面的配置选项：

🔐 身份验证类型

将 DB_AUTHENTICATION_TYPE 设置为以下之一：

  • sql - SQL Server 身份验证（默认）
  • windows - Windows 身份验证
  • azure-ad - Azure Active Directory 身份验证

📋 完整的环境变量

变量 描述 默认值 适用场景
基本连接
DB_AUTHENTICATION_TYPE 身份验证类型 (sql/windows/azure-ad) sql 所有
DB_SERVER SQL Server 主机名/IP - 所有
DB_NAME 数据库名称 - 所有
DB_PORT SQL Server 端口 1433 所有
DB_TIMEOUT 连接超时时间 (ms) 30000 所有
DB_REQUEST_TIMEOUT 请求超时时间 (ms) 30000 所有
SQL Server 身份验证
DB_USER SQL Server 用户名 - SQL 身份验证
DB_PASSWORD SQL Server 密码 - SQL 身份验证
Windows 身份验证
DB_DOMAIN Windows 域名 - Windows 身份验证
DB_USER Windows 用户名 当前用户 Windows 身份验证
DB_PASSWORD Windows 密码 - Windows 身份验证
Azure AD 身份验证
DB_USER Azure AD 用户名 - Azure AD（密码）
DB_PASSWORD Azure AD 密码 - Azure AD（密码）
DB_AZURE_CLIENT_ID Azure AD 应用客户端 ID - Azure AD（服务主体）
DB_AZURE_CLIENT_SECRET Azure AD 应用客户端密钥 - Azure AD（服务主体）
DB_AZURE_TENANT_ID Azure AD 租户 ID - Azure AD（服务主体）
SQL Server Express
DB_INSTANCE_NAME 命名实例（例如，SQLEXPRESS） - Express 实例
安全设置
DB_ENCRYPT 启用加密 false 所有
DB_TRUST_SERVER_CERTIFICATE 信任服务器证书 false 所有
DB_ENABLE_ARITH_ABORT 启用算术中止 true 所有
DB_USE_UTC 日期使用 UTC true 所有
连接池
DB_POOL_MAX 最大连接数 10 所有
DB_POOL_MIN 最小连接数 0 所有
DB_POOL_IDLE_TIMEOUT 空闲超时时间 (ms) 30000 所有
高级设置
DB_CANCEL_TIMEOUT 取消超时时间 (ms) 5000 所有
DB_PACKET_SIZE 数据包大小 (字节) 4096 所有
DB_CONNECTION_STRING 完整的连接字符串 - 替代单独设置

连接配置示例

1. 🏠 SQL Server 本地（SQL 身份验证）

{
"mcpServers": {
"mcpql": {
"command": "npx",
"args": ["-y", "hendrickcastro/mcpql"],
"env": {
"DB_AUTHENTICATION_TYPE": "sql",
"DB_SERVER": "localhost",
"DB_NAME": "MyDatabase",
"DB_USER": "sa",
"DB_PASSWORD": "YourPassword123!",
"DB_PORT": "1433",
"DB_ENCRYPT": "false",
"DB_TRUST_SERVER_CERTIFICATE": "true"
}
}
}
}

2. 🏢 SQL Server Express（命名实例）

{
"mcpServers": {
"mcpql": {
"command": "npx",
"args": ["-y", "hendrickcastro/mcpql"],
"env": {
"DB_AUTHENTICATION_TYPE": "sql",
"DB_SERVER": "localhost",
"DB_INSTANCE_NAME": "SQLEXPRESS",
"DB_NAME": "MyDatabase",
"DB_USER": "sa",
"DB_PASSWORD": "YourPassword123!",
"DB_ENCRYPT": "false",
"DB_TRUST_SERVER_CERTIFICATE": "true"
}
}
}
}

3. 🪟 Windows 身份验证

{
"mcpServers": {
"mcpql": {
"command": "npx",
"args": ["-y", "hendrickcastro/mcpql"],
"env": {
"DB_AUTHENTICATION_TYPE": "windows",
"DB_SERVER": "MYSERVER",
"DB_NAME": "MyDatabase",
"DB_DOMAIN": "MYDOMAIN",
"DB_USER": "myuser",
"DB_PASSWORD": "mypassword",
"DB_ENCRYPT": "false",
"DB_TRUST_SERVER_CERTIFICATE": "true"
}
}
}
}

4. ☁️ Azure SQL 数据库（Azure AD 密码）

{
"mcpServers": {
"mcpql": {
"command": "npx",
"args": ["-y", "hendrickcastro/mcpql"],
"env": {
"DB_AUTHENTICATION_TYPE": "azure-ad",
"DB_SERVER": "myserver.database.windows.net",
"DB_NAME": "MyDatabase",
"DB_USER": "user@domain.com",
"DB_PASSWORD": "userpassword",
"DB_PORT": "1433",
"DB_ENCRYPT": "true",
"DB_TRUST_SERVER_CERTIFICATE": "false"
}
}
}
}

5. 🔐 Azure SQL 数据库（服务主体）

{
"mcpServers": {
"mcpql": {
"command": "npx",
"args": ["-y", "hendrickcastro/mcpql"],
"env": {
"DB_AUTHENTICATION_TYPE": "azure-ad",
"DB_SERVER": "myserver.database.windows.net",
"DB_NAME": "MyDatabase",
"DB_AZURE_CLIENT_ID": "your-client-id",
"DB_AZURE_CLIENT_SECRET": "your-client-secret",
"DB_AZURE_TENANT_ID": "your-tenant-id",
"DB_PORT": "1433",
"DB_ENCRYPT": "true",
"DB_TRUST_SERVER_CERTIFICATE": "false"
}
}
}
}

6. 🔗 使用连接字符串

{
"mcpServers": {
"mcpql": {
"command": "npx",
"args": ["-y", "hendrickcastro/mcpql"],
"env": {
"DB_CONNECTION_STRING": "Server=localhost;Database=MyDatabase;User Id=sa;Password=YourPassword123!;Encrypt=false;TrustServerCertificate=true;"
}
}
}
}

🚨 常见问题排查

连接问题

  • “登录失败”：检查用户名/密码。对于 Windows 身份验证，请确保 DB_AUTHENTICATION_TYPE=windows
  • “未找到服务器”：验证服务器名称和端口。对于 SQL Express，请添加 DB_INSTANCE_NAME
  • “证书”错误：对于本地开发，设置 DB_TRUST_SERVER_CERTIFICATE=true
  • 超时错误：增加 DB_TIMEOUT 或检查网络连接

SQL Server Express 设置

  1. 在 SQL Server 配置管理器中启用 TCP/IP 协议
  2. 设置静态端口（通常为 1433）或使用带有浏览器服务的动态端口
  3. 配置 Windows 防火墙以允许 SQL Server 流量
  4. 对于默认的 Express 安装，使用 DB_INSTANCE_NAME=SQLEXPRESS

Azure SQL 数据库设置

  1. 创建服务器防火墙规则以允许客户端 IP
  2. 服务器名称使用格式：server.database.windows.net
  3. 始终设置 DB_ENCRYPT=true 和 DB_TRUST_SERVER_CERTIFICATE=false
  4. 对于服务主体身份验证，在 Azure AD 中注册应用并分配权限

🧪 测试

运行全面的测试套件：

npm test

测试套件包括对所有 10 种工具的全面测试，使用真实数据库进行测试并实现了完全覆盖。

🏗️ 架构

项目结构

MCPQL/
├── src/
│   ├── __tests__/          # 全面的测试套件
│   ├── tools/              # 模块化工具实现
│   │   ├── tableAnalysis.ts      # 表分析工具
│   │   ├── storedProcedureAnalysis.ts  # 存储过程分析工具
│   │   ├── dataOperations.ts     # 数据操作工具
│   │   ├── objectSearch.ts       # 搜索和发现工具
│   │   ├── types.ts              # 类型定义
│   │   └── index.ts              # 工具导出
│   ├── db.ts               # 数据库连接管理
│   ├── server.ts           # MCP 服务器设置和处理程序
│   ├── tools.ts            # 工具定义和模式
│   └── mcp-server.ts       # 工具重新导出
├── dist/                   # 编译后的 JavaScript 输出
└── package.json           # 依赖项和脚本

关键特性

  • ⚡ 连接池：高效的数据库连接管理
  • 🛡️ 强大的错误处理：全面的错误处理和验证
  • 📋 丰富的元数据：详细的结果，包含全面的数据库信息
  • 🔧 灵活的配置：基于环境的配置
  • 📊 优化的查询：所有操作都采用高效的 SQL 查询

📝 重要提示

⚠️ 重要提示

  • 对象名称：始终使用带架构限定的名称（例如，dbo.Users、api.Idiomas）
  • 错误处理：所有工具都返回带有成功/错误指示的结构化响应
  • 类型安全：完全支持 TypeScript，并提供适当的类型定义
  • 连接管理：自动连接池和重试逻辑
  • 安全性：使用参数化查询以防止 SQL 注入

🤝 贡献

  1. 分叉仓库
  2. 创建功能分支 (git checkout -b feature/amazing-feature)
  3. 进行更改并添加测试
  4. 确保所有测试通过 (npm test)
  5. 提交更改 (git commit -m 'Add amazing feature')
  6. 推送到分支 (git push origin feature/amazing-feature)
  7. 打开拉取请求

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

🙏 致谢

🏷️ 标签与关键词

数据库： sql-server azure-sql database-analysis database-tools mssql t-sql database-management database-administration database-operations data-analysis

MCP 与 AI： model-context-protocol mcp-server mcp-tools ai-tools claude-desktop cursor-ide anthropic llm-integration ai-database intelligent-database

技术： typescript nodejs npm-package cli-tool database-client sql-client database-sdk rest-api json-api database-connector

特性： table-analysis stored-procedures data-preview column-statistics query-execution database-search object-dependencies schema-analysis data-exploration database-insights

部署： docker azure-deployment cloud-ready enterprise-ready production-ready scalable secure authenticated encrypted configurable

用例： database-development data-science business-intelligence database-migration schema-documentation performance-analysis data-governance database-monitoring troubleshooting automation

🎯 MCPQL 通过模型上下文协议提供全面的 SQL Server 数据库分析和操作功能。非常适合数据库管理员、开发人员以及任何使用 SQL Server 数据库的人员！ 🚀

默认排序 时间排序

0 个评论

  • 0 关注
  • 0 收藏，10 浏览
  • system 提出于 2025-09-24 23:09

相似服务问题

热议话题 »