Mcpql

🚀 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

2. 配置数据库连接： 创建一个 .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

3. 使用本地路径配置 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 身份验证

📋 完整的环境变量

连接配置示例

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 文件。

🙏 致谢

• 使用 Model Context Protocol SDK 构建
• 使用 mssql 进行 SQL Server 连接
• 使用 Jest 进行全面测试

🏷️ 标签与关键词

数据库： 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 数据库的人员！ 🚀