使用说明

MSSQL模型上下文协议（MCP）服务器

用于Microsoft SQL server数据库的模型上下文协议服务器的Node.js实现。该服务器提供了一个标准化的API接口来与SQL server数据库交互，将数据库表公开为资源，并提供执行SQL查询和检索模式信息的工具。

多数据库支持

此项目现在具有自动配置检测功能，允许其在两种模式下工作：

单数据库模式 -使用简单 MSSQL_* 连接到一个数据库的变量
多数据库模式 -使用前缀环境变量(MSSQL_<DBNAME>_*)使用自定义名称连接到多个数据库

服务器在运行时自动检测哪个模式处于活动状态，并在任何一种情况下都公开相同的REST/MCP接口。在多数据库模式下，您可以使用您喜欢的任何数据库名称（例如。， MSSQL_MAINDB_*, MSSQL_REPORTINGDB_*, MSSQL_ANALYTICS_*, MSSQL_CUSTOMERS_*等等）。

环境配置

单数据库模式

# Single database configuration
MSSQL_SERVER=your_sql_server_address
MSSQL_PORT=1433
MSSQL_USER=your_username
MSSQL_PASSWORD=your_password
MSSQL_DATABASE=your_database_name
MSSQL_ENCRYPT=true
MSSQL_TRUST_SERVER_CERTIFICATE=false

多数据库模式

# Main database
MSSQL_MAINDB_SERVER=your_sql_server_address
MSSQL_MAINDB_PORT=1433
MSSQL_MAINDB_USER=your_username
MSSQL_MAINDB_PASSWORD=your_password
MSSQL_MAINDB_DATABASE=main_db_name
MSSQL_MAINDB_ENCRYPT=true
MSSQL_MAINDB_TRUST_SERVER_CERTIFICATE=false

# Reporting database
MSSQL_REPORTINGDB_SERVER=your_sql_server_address
MSSQL_REPORTINGDB_PORT=1433
MSSQL_REPORTINGDB_USER=your_username
MSSQL_REPORTINGDB_PASSWORD=your_password
MSSQL_REPORTINGDB_DATABASE=reporting_db_name
MSSQL_REPORTINGDB_ENCRYPT=true
MSSQL_REPORTINGDB_TRUST_SERVER_CERTIFICATE=false

自定义数据库名称示例

您可以按照以下模式使用任何您喜欢的数据库名称 MSSQL_<YOUR_CUSTOM_NAME>_*:

# Analytics database
MSSQL_ANALYTICS_SERVER=analytics.example.com
MSSQL_ANALYTICS_PORT=1433
MSSQL_ANALYTICS_USER=analytics_user
MSSQL_ANALYTICS_PASSWORD=analytics_password
MSSQL_ANALYTICS_DATABASE=analytics_data
MSSQL_ANALYTICS_ENCRYPT=true
MSSQL_ANALYTICS_TRUST_SERVER_CERTIFICATE=false

# Customer database
MSSQL_CUSTOMERS_SERVER=customers.example.com
MSSQL_CUSTOMERS_PORT=1433
MSSQL_CUSTOMERS_USER=customer_user
MSSQL_CUSTOMERS_PASSWORD=customer_password
MSSQL_CUSTOMERS_DATABASE=customer_data
MSSQL_CUSTOMERS_ENCRYPT=true
MSSQL_CUSTOMERS_TRUST_SERVER_CERTIFICATE=false

服务器将自动检测遵循此模式的任何数据库配置，并使用小写键使其可用（例如。， analytics, customers).

重要提示： 在您的数据库中配置单个数据库或多个数据库变量 .env 文件-不是两者都有。服务器根据特定变量的存在来检测使用哪种模式。

配置和行为矩阵

启动配置	环境设置	行为
mssql-mcp节点单	单数据库变量	使用一个数据库在单数据库模式下运行
mssql-mcp节点多	多数据库变量	在多数据库模式下操作多个数据库

默认dbKey行为

在多数据库模式下，当没有 dbKey 如果在请求中指定，服务器将自动按字母顺序使用配置中的第一个数据库。这使得API请求更加简洁，同时保持向后兼容性。

特性

自动检测配置模式：自动确定是使用单数据库模式还是多数据库模式
资源管理：将SQL Server表作为资源访问
SQL查询执行：对连接的数据库执行SQL查询
架构信息：检索数据库表的元数据和架构详细信息
MCP协议支持：使用模型上下文协议SDK通过STDIO进行通信
HTTP API：用于使用Express进行本地测试
增强验证：使用Zod进行稳健的输入验证，并显示清晰的错误消息
安全功能：参数化查询和SQL注入保护

安装

先决条件

Node.js（v14或更高版本）
访问Microsoft SQL Server数据库

步骤

克隆存储库

git clone https://github.com/mihai-dulgheru/mssql-mcp-node.git
cd mssql-mcp-node

再进行
```
npm install
```
配置环境变量

复制示例环境配置并根据需要进行更新：
```
cp .env.example .env
```
然后，更新 .env 使用单数据库或多数据库格式（见上文）将SQL Server连接详细信息保存在文件中。
安全建议：
- 发展：
  - MSSQL_ENCRYPT="false" 或 MSSQL_*DB_ENCRYPT="false"
  - MSSQL_TRUST_SERVER_CERTIFICATE="true" 或 MSSQL_*DB_TRUST_SERVER_CERTIFICATE="true"
- 生产：
  - MSSQL_ENCRYPT="true" 或 MSSQL_*DB_ENCRYPT="true" （加密连接）
  - MSSQL_TRUST_SERVER_CERTIFICATE="false" 或 MSSQL_*DB_TRUST_SERVER_CERTIFICATE="false" （强制证书验证）

用法

有两种操作模式：

1.MCP模式（STDIO）

此模式使用带有STDIO传输的模型上下文协议（MCP）SDK，旨在与Claude Desktop或VS Code等客户端集成。

启动MCP模式：
```
npm start
```
这将从以下位置运行MCP服务器 src/index.js.

2.HTTP模式（Express）

对于通过HTTP进行的本地测试，您可以启动暴露API端点的Express服务器。

启动快速模式：
```
npm run start:express
```
这将运行中定义的Express服务器 src/express.js.
自动重载开发模式：
```
npm run dev:express
```

API端点（快速模式）

列出资源（表）：

GET /resources?dbKey=maindb

示例响应：

[
  {
    "uri": "mssql://YourTable/data",
    "name": "Table: YourTable",
    "description": "Data in table: YourTable (DB: your_database)",
    "mimeType": "text/plain"
  }
]

获取资源数据：

GET /resource?uri=mssql://YourTable/data&dbKey=maindb

示例响应：

# Database: your_database
id,name,created_at
1,Item1,2025-01-01
2,Item2,2025-01-02

列出可用工具：

GET /tools

示例响应：

[
  {
    "name": "execute_sql",
    "description": "Execute an SQL query on the SQL Server (multi-database support)",
    "inputSchema": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "The SQL query to execute"
        },
        "dbKey": {
          "type": "string",
          "description": "The database key to use (e.g., 'maindb', 'reportingdb', etc.). Optional in single-db mode."
        }
      },
      "required": ["query"]
    }
  },
  {
    "name": "get_table_schema",
    "description": "Retrieve the schema of a specified table (multi-database support)",
    "inputSchema": {
      "type": "object",
      "properties": {
        "table": {
          "type": "string",
          "description": "The name of the table"
        },
        "dbKey": {
          "type": "string",
          "description": "The database key to use (e.g., 'maindb', 'reportingdb', etc.). Optional in single-db mode."
        }
      },
      "required": ["table"]
    }
  }
]

执行SQL查询：

POST /execute-sql

请求正文：

{
  "query": "SELECT TOP 10 * FROM YourTable",
  "dbKey": "maindb" // Optional, defaults to first configured database
}

SELECT查询的响应示例：

{
  "db": "your_database",
  "rowCount": 2,
  "recordset": [
    { "id": 1, "name": "Item1", "created_at": "2025-01-01" },
    { "id": 2, "name": "Item2", "created_at": "2025-01-02" }
  ]
}

非SELECT查询的响应示例：

{
  "message": "Query executed successfully",
  "db": "your_database",
  "rowsAffected": 1
}

获取表架构：

POST /get-table-schema

请求正文：

{
  "table": "YourTable",
  "dbKey": "reportingdb" // Optional, defaults to first configured database
}

响应示例：

{
  "db": "reporting_db_name",
  "table": "YourTable",
  "columns": [
    {
      "COLUMN_NAME": "id",
      "DATA_TYPE": "int",
      "CHARACTER_MAXIMUM_LENGTH": null
    },
    {
      "COLUMN_NAME": "name",
      "DATA_TYPE": "varchar",
      "CHARACTER_MAXIMUM_LENGTH": 100
    },
    {
      "COLUMN_NAME": "created_at",
      "DATA_TYPE": "datetime",
      "CHARACTER_MAXIMUM_LENGTH": null
    }
  ],
  "rowCount": 3
}

与Claude Desktop或VS Code集成

要将此MCP服务器与Claude Desktop或VS Code集成，请将以下JSON代码段添加到MCP配置文件中。对于Claude Desktop来说，这通常是 mcpServers.json，对于VS Code，在您的工作区配置中(.vscode/mcp.json).

VS代码

对于VS Code 1.86.0及更高版本，请使用单数据库或多数据库配置：

单个数据库配置

{
  "servers": {
    "mssql-mcp-node-single": {
      "command": "npx",
      "args": ["-y", "mssql-mcp-node"],
      "env": {
        "MSSQL_SERVER": "your_server_name",
        "MSSQL_PORT": "1433",
        "MSSQL_USER": "your_username",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_DATABASE": "your_database",
        "MSSQL_ENCRYPT": "true",
        "MSSQL_TRUST_SERVER_CERTIFICATE": "false"
      }
    }
  }
}

多数据库配置

{
  "servers": {
    "mssql-mcp-node-multi": {
      "command": "npx",
      "args": ["-y", "mssql-mcp-node"],
      "env": {
        "MSSQL_MAINDB_SERVER": "your_server_name",
        "MSSQL_MAINDB_PORT": "1433",
        "MSSQL_MAINDB_USER": "your_username",
        "MSSQL_MAINDB_PASSWORD": "your_password",
        "MSSQL_MAINDB_DATABASE": "main_database",
        "MSSQL_MAINDB_ENCRYPT": "true",
        "MSSQL_MAINDB_TRUST_SERVER_CERTIFICATE": "false",

        "MSSQL_REPORTINGDB_SERVER": "your_server_name",
        "MSSQL_REPORTINGDB_PORT": "1433",
        "MSSQL_REPORTINGDB_USER": "your_username",
        "MSSQL_REPORTINGDB_PASSWORD": "your_password",
        "MSSQL_REPORTINGDB_DATABASE": "reporting_database",
        "MSSQL_REPORTINGDB_ENCRYPT": "true",
        "MSSQL_REPORTINGDB_TRUST_SERVER_CERTIFICATE": "false"
      }
    }
  }
}

您也可以在本地安装此软件包，而不是使用 npx:

npm install --save-dev mssql-mcp-node

MCP工具

通过Claude Desktop或VS Code集成使用MCP服务器时，您可以使用以下工具：

execute_sql

对连接的数据库执行SQL查询。

输入：

{
  "query": "SELECT TOP 10 * FROM YourTable",
  "dbKey": "maindb" // Optional in both modes, defaults to first available database
}

Claude Desktop中的示例用法：

I'd like to see data from the YourTable table in the main database.

get_table_schema

检索特定表的架构信息。

输入：

{
  "table": "YourTable",
  "dbKey": "reportingdb" // Optional in both modes, defaults to first available database
}

Claude Desktop中的示例用法：

What columns are in the YourTable table in the reporting database?

列表_数据库

列出所有已配置的数据库及其连接信息。

输入：

{}


// No parameters required

Claude Desktop中的示例用法：

Show me all the available databases in the configuration.

测试

邮递员收藏在 postman/ 用于测试Express服务器的HTTP端点的文件夹。以下是测试单数据库和多数据库配置的curl示例：

卷曲测试

测试所有四种组合（单/多数据库模式×maindb/reportingdb）：

单数据库模式（仅限一个数据库）

# List Resources
curl -X GET "http://localhost:3000/resources"

# Execute SQL Query
curl -X POST "http://localhost:3000/execute-sql" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT TOP 10 * FROM Users"}'

# Get Table Schema
curl -X POST "http://localhost:3000/get-table-schema" \
  -H "Content-Type: application/json" \
  -d '{"table": "Users"}'

多数据库模式

# List Resources from maindb
curl -X GET "http://localhost:3000/resources?dbKey=maindb"

# List Resources from reportingdb
curl -X GET "http://localhost:3000/resources?dbKey=reportingdb"

# Execute SQL Query on maindb
curl -X POST "http://localhost:3000/execute-sql" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT TOP 10 * FROM Users", "dbKey": "maindb"}'

# Execute SQL Query on reportingdb
curl -X POST "http://localhost:3000/execute-sql" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT TOP 10 * FROM SalesReport", "dbKey": "reportingdb"}'

架构验证

此项目使用萨德用于整个应用程序的模式验证，以确保数据完整性并提供更稳健的错误处理。

已实现的架构验证

SQL查询验证：验证SQL查询是否为合理长度限制内的非空字符串。
表名验证：确保表名遵循正确的命名约定（仅限字母数字字符和下划线）。
资源URI验证：验证资源URI是否遵循预期格式(mssql://<table_name>/data).
数据库配置验证：确保提供所有必需的数据库配置参数并正确格式化。
安全检查：SQL查询会根据潜在危险操作列表进行验证，以提高安全性。

增强的安全性

SQL注入保护：尽可能使用参数化查询。
查询安全验证：检查潜在危险的SQL操作（DROP、TRUNCATE等）
增强的错误消息：提供详细但安全的错误消息，不会暴露敏感细节。
配置验证：在尝试连接之前验证所有配置参数。

项目结构

mssql-mcp-node/
├── .editorconfig
├── .env                  # Environment variables file (not committed)
├── .env.example          # Sample environment configuration (both modes)
├── .gitignore
├── .markdownlint.json
├── .prettierignore
├── .prettierrc
├── eslint.config.mjs
├── LICENSE
├── node_modules/
├── package-lock.json
├── package.json
├── postman/              # Postman collection for API testing
├── README.md
└── src/
    ├── config/
    │   ├── dbConfig.js    # Database connection handling module
    │   └── index.js       # Configuration auto-detection module
    ├── express.js         # Entry point for Express server (HTTP mode)
    ├── index.js           # MCP server entry point (STDIO mode via SDK)
    ├── modules/           # Core modules (resource and tool management)
    │   ├── resources.js   # Functions for listing resources and reading table data
    │   └── tools.js       # Functions for SQL operations
    ├── server/            # Express server setup (used by express.js)
    │   └── index.js       # Express server implementation
    └── validation/        # Schema validation module using Zod
        └── index.js       # Schema definitions and validation functions

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

作者

米哈伊·尼古拉·杜尔格鲁 mihai.dulgheru18@gmail.com

使用说明

MSSQL模型上下文协议（MCP）服务器

多数据库支持

环境配置

单数据库模式

多数据库模式

自定义数据库名称示例

配置和行为矩阵

默认dbKey行为

特性

安装

先决条件

步骤

用法

1.MCP模式（STDIO）

2.HTTP模式（Express）

API端点（快速模式）

与Claude Desktop或VS Code集成

VS代码

单个数据库配置

多数据库配置

MCP工具

execute_sql

get_table_schema

列表_数据库

测试

卷曲测试

单数据库模式（仅限一个数据库）

多数据库模式

架构验证

已实现的架构验证

增强的安全性

项目结构

许可证

作者

相关 MCP

MySQL数据库管理工具

MongoDB 数据库 MCP 服务器

PostgreSQL管理服务器

PocketBase 数据库 MCP 服务器

SQLite数据库服务

MySQL数据库操作工具