facturas-mcp

一个只读 MCP 服务器，用于让 Claude Desktop 查询 DWH.facturas。

工作原理

• Claude Desktop 在本地启动此服务器（独立进程，通过 stdio 通信）。

• 服务器使用一个只读登录名（mcp_readonly）连接到 SQL Server，该登录名仅对 DWH.facturas 拥有 GRANT SELECT 权限。该权限存在于数据库中，而不是在这段代码里--这才是真正的安全屏障。

• 提供两个工具：

  • listar_columnas_facturas：让 Claude 在编写 SQL 之前发现有哪些列。

  • consultar_facturas：对 DWH.facturas 执行只读 SELECT。

Related MCP server: MSSQL Database MCP Server

第 1 步 -- 在 SQL Server 中创建受限登录名

使用一个对数据库拥有管理权限的用户，只运行一次 setup-db-login.sql。运行前请修改示例密码。

第 2 步 -- 配置此服务器的凭据

在此文件夹中创建一个 .env 文件（不会提交到 git），内容如下：

MSSQL_SERVER=sintesiserp.com
MSSQL_DATABASE=Diverxamotos_4_2
MSSQL_USER=mcp_readonly
MSSQL_PASSWORD=la-contrasena-que-pusiste-en-el-paso-1

第 3 步 -- 在 Claude Desktop 中注册服务器

打开 claude_desktop_config.json（在 Windows 上：%APPDATA%\Claude\claude_desktop_config.json），然后在 "mcpServers" 中添加以下内容：

{
  "mcpServers": {
    "facturas": {
      "command": "node",
      "args": ["C:\\Users\\Developer-07\\Documents\\DESARROLLO\\facturas-mcp\\dist\\index.js"],
      "env": {
        "MSSQL_SERVER": "sintesiserp.com",
        "MSSQL_DATABASE": "Diverxamotos_4_2",
        "MSSQL_USER": "mcp_readonly",
        "MSSQL_PASSWORD": "la-contrasena-que-pusiste-en-el-paso-1"
      }
    }
  }
}

完全关闭 Claude Desktop，然后重新打开，以便加载新服务器。

第 4 步 -- 测试

在 Claude Desktop 中，问一个类似这样的问题：“根据 DWH.facturas，我今天卖了多少？”

之后添加另一张表

1. 在 SQL Server 中：GRANT SELECT ON DWH.otratabla TO mcp_readonly;

2. 在 src/index.ts 中：将 "DWH.OTRATABLA" 添加到 ALLOWED_TABLES 数组，并可选择添加一个与现有工具相同的 listar_columnas_otratabla 工具。

3. 运行 npm run build，然后重启 Claude Desktop。

远程模式（Render）-- 让多人从 Claude.ai 使用

默认情况下，服务器以 stdio 模式运行（本地模式，每个用户一个进程，由 Claude Desktop 启动）。为了让多人无需安装任何东西就能从 Claude.ai 使用它，可以将其作为 HTTP 服务部署到 Render。同一个 dist/index.js 可用于两种模式--切换开关是环境变量 MCP_TRANSPORT。

重要： 在 HTTP 模式下，数据库的唯一保护仍然是只读登录名，但 MCP 服务器本身 会暴露在公共 URL 上。因此 HTTP 模式要求使用令牌（MCP_AUTH_TOKEN）--没有它，进程甚至无法启动。任何同时拥有 URL 和 令牌的人都可以对 DWH.facturas 执行 SELECT，所以请将该令牌视为密码：不要公开它，不要把它提交到 git，如果泄露就轮换它。

第 1 步 -- 生成一个强令牌

例如，使用 PowerShell：

-join ((48..57)+(65..90)+(97..122)|Get-Random -Count 40|%{[char]$_})

保存该值--它就是你的 MCP_AUTH_TOKEN。

第 2 步 -- 在 Render 中创建 Web Service

1. 将此项目上传到 GitHub 仓库（node_modules 和 dist 不需要在仓库中--它们已经在 .gitignore 里--Render 会自行运行 npm install 和 npm run build）。

2. 在 Render 中：New -> Web Service，然后连接仓库。

3. Build Command: npm install && npm run build

4. Start Command: npm start

5. Environment variables（Environment 选项卡）：

   MCP_TRANSPORT=http
   MCP_AUTH_TOKEN=<el token del paso 1>
   MSSQL_SERVER=sintesiserp.com
   MSSQL_DATABASE=Diverxamotos_4_2
   MSSQL_USER=mcp_readonly
   MSSQL_PASSWORD=<la contrasena del login de solo lectura>

   （Render 会自动定义 PORT--无需手动添加。）

6. 部署。完成后，Render 会给你一个类似 https://facturas-mcp.onrender.com 的 URL。

第 3 步 -- 测试服务器是否响应

curl https://facturas-mcp.onrender.com/health
# {"status":"ok"}

curl -X POST https://facturas-mcp.onrender.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <tu MCP_AUTH_TOKEN>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

如果它返回 serverInfo 和 capabilities，说明服务器已启动并接受该令牌。如果没有正确的 Authorization 请求头，它应返回 401。

第 4 步 -- 从 Claude.ai / Claude Desktop 连接

在 Claude.ai（或较新版本的 Claude Desktop）中：Settings -> Connectors -> Add custom connector，然后注册 URL https://facturas-mcp.onrender.com/mcp，并带上认证头 Authorization: Bearer <tu MCP_AUTH_TOKEN>（具体 UI 可能因 Claude 版本而异--请查找“远程 MCP 服务器 / custom connector”选项）。

注意：Render 的免费方案会在闲置后“休眠”服务--休眠后的第一个请求可能需要几秒钟才能响应。