Mcpql SQL Server MCP Server

MCPQL-SQL Server MCP

全面 模型上下文协议（MCP） 服务器 SQL Server 数据库操作。该服务器通过MCP协议为数据库分析、对象发现和数据操作提供了10个强大的工具。

🚀 快速开始

先决条件

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

安装和配置

选项1：使用GitHub上的npx（推荐）

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

适用于克劳德桌面(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"
      }
    }
  }
}

对于游标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 包含数据库凭据的文件：

# Basic SQL Server connection
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数据库操作提供了11个全面的工具：

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

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

11. 🔒 安全状态 - mcp_get_security_status

获取数据库操作的当前安全配置和状态。

📋 使用示例

分析表格

// Get complete table structure
const analysis = await mcp_table_analysis({ 
  table_name: "dbo.Users" 
});

// Get quick data overview
const overview = await mcp_quick_data_analysis({ 
  table_name: "dbo.Users",
  sample_size: 500
});

// Preview table data with filters
const data = await mcp_preview_data({
  table_name: "dbo.Users",
  filters: { "Status": "Active", "Department": "IT" },
  limit: 25
});

查找数据库对象

// Find all objects containing "User"
const objects = await mcp_search_comprehensive({ 
  pattern: "User",
  search_in_names: true,
  search_in_definitions: false
});

// Find procedures that query a specific table
const procedures = await mcp_search_comprehensive({ 
  pattern: "FROM Users",
  object_types: ["PROCEDURE"],
  search_in_definitions: true
});

分析存储过程

// Get complete stored procedure analysis
const spAnalysis = await mcp_sp_structure({ 
  sp_name: "dbo.usp_GetUserData" 
});

// Execute a stored procedure
const result = await mcp_execute_procedure({
  sp_name: "dbo.usp_GetUserById",
  params: { "UserId": 123, "IncludeDetails": true }
});

数据分析

// Get column statistics
const stats = await mcp_get_column_stats({
  table_name: "dbo.Users",
  column_name: "Age"
});

// Get sample values from a column
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.🪟 身份验证

{
  "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;"
      }
    }
  }
}

🔒 安全功能

MCPQL包括全面的安全控制，以防止意外的数据库修改，这在生产环境中尤为重要。

🛡️ 安全控制

数据库修改保护

• DB_ALLOW_MODIFICATIONS：控制DML/DDL操作（INSERT、UPDATE、DELETE、ALTER、DROP、CREATE）
• DB_ALLOW_STORED_PROCEDURES：控制存储过程执行
• 默认：两个变量默认为 false 为了最大限度的安全

安全状态工具

使用 mcp_get_security_status 要检查当前的安全配置，请执行以下操作：

const status = await mcp_get_security_status({});

🔧 启用操作

开发环境

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_SERVER": "localhost",
        "DB_NAME": "MyDatabase",
        "DB_USER": "sa",
        "DB_PASSWORD": "YourPassword123!",
        "DB_ALLOW_MODIFICATIONS": "true",
        "DB_ALLOW_STORED_PROCEDURES": "true"
      }
    }
  }
}

生产环境（推荐）

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_SERVER": "prod-server",
        "DB_NAME": "ProductionDB",
        "DB_USER": "readonly_user",
        "DB_PASSWORD": "secure_password",
        "DB_ALLOW_MODIFICATIONS": "false",
        "DB_ALLOW_STORED_PROCEDURES": "false"
      }
    }
  }
}

🚨 安全错误消息

当操作被阻止时，MCPQL提供了明确的指导：

Error: Modification operations are disabled for security.
To enable modifications, configure: DB_ALLOW_MODIFICATIONS=true

Error: Stored procedure execution is disabled for security.
To enable stored procedures, configure: DB_ALLOW_STORED_PROCEDURES=true

📋 始终允许的操作

无论安全设置如何，这些操作始终是允许的：

• SELECT查询
• 表分析和模式检查
• 列统计和数据预览
• 对象搜索和依赖关系分析
• 数据库元数据操作

有关完整的安全文档，请参阅 安全.md.

🚨 常见问题排查

连接问题

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

SQL Server Express安装程序

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

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__/          # Comprehensive test suite
│   ├── tools/              # Modular tool implementations
│   │   ├── tableAnalysis.ts      # Table analysis tools
│   │   ├── storedProcedureAnalysis.ts  # SP analysis tools
│   │   ├── dataOperations.ts     # Data operation tools
│   │   ├── objectSearch.ts       # Search and discovery tools
│   │   ├── types.ts              # Type definitions
│   │   └── index.ts              # Tool exports
│   ├── db.ts               # Database connection management
│   ├── server.ts           # MCP server setup and handlers
│   ├── tools.ts            # Tool definitions and schemas
│   └── mcp-server.ts       # Tool re-exports
├── dist/                   # Compiled JavaScript output
└── package.json           # Dependencies and scripts

主要特点

• ⚡ 连接池：高效的数据库连接管理
• 🛡️ 稳健的错误处理：全面的错误处理和验证
• 📋 元数据：详细的结果和全面的数据库信息
• 🔧 灵活的配置：基于环境的配置
• 📊 优化查询：所有操作的高效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许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 与 模型上下文协议SDK
• 用途 数据库 用于SQL Server连接
• 全面测试 开玩笑

🏷️ 标签和关键字

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