Skip to main content
Glama
Sign In
deenesjakoruzh
facturas-mcp

facturas-mcp

by Andres2009
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

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: Microsoft SQL Server 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 的免费方案会在闲置后“休眠”服务--休眠后的第一个请求可能需要几秒钟才能响应。

Available Tools

2 tools
consultar_facturasA

Ejecuta una consulta SQL de solo lectura (SELECT) contra la tabla DWH.facturas para responder preguntas de negocio (ventas del dia, totales por cliente, facturas de un periodo, etc). Solo se permite SELECT sobre DWH.facturas -- cualquier otra cosa se rechaza. Si no conoces las columnas de la tabla, usa primero la herramienta listar_columnas_facturas.

NameRequiredDescriptionDefault
sqlYesConsulta SQL SELECT contra DWH.facturas. Ejemplo: SELECT SUM(valor) AS total FROM DWH.facturas WHERE fecha = '2026-08-19'

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No hay anotaciones, por lo que la descripción asume la responsabilidad de informar el comportamiento. Revela que solo es una operación de lectura, que acepta únicamente SELECT y que cualquier otra consulta será rechazada. Esto es un contexto conductual valioso, aunque no detalla formato de respuesta ni límites de ejecución.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tres oraciones con información esencial y sin relleno. La restricción crítica (solo SELECT) está al frente, y la referencia a la herramienta hermana es breve y pertinente.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Para una herramienta de un solo parámetro, la descripción cubre el propósito, las restricciones de uso y el paso a seguir si falta conocimiento de columnas. No hay anotaciones ni esquema de salida, pero el contexto entregado es suficiente para que el agente invoque la herramienta correctamente.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

El esquema cubre el 100% del parámetro sql y ya incluye descripción y ejemplo, así que la descripción no necesita añadir mucho. La descripción refuerza que el SQL debe ser SELECT y contra DWH.facturas, pero no agrega detalles semánticos nuevos más allá del esquema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

La descripción usa un verbo específico ('Ejecuta una consulta SQL de solo lectura') y un recurso concreto ('tabla DWH.facturas'), dejando claro qué hace la herramienta. Además, la diferencia de la herramienta hermana listar_columnas_facturas al indicar que ésta es para consultar datos, no para conocer columnas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Indica explícitamente cuándo usarla: para responder preguntas de negocio que requieran datos de DWH.facturas. También establece exclusions ('solo se permite SELECT... cualquier otra cosa se rechaza') y recomienda usar listar_columnas_facturas cuando no se conocen las columnas, lo que orienta claramente al agente.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listar_columnas_facturasA

Devuelve el nombre y tipo de cada columna de la tabla DWH.facturas. Usa esta herramienta primero, antes de escribir una consulta, si no conoces el esquema de la tabla.

NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of disclosing behavior. It clearly indicates a read-only metadata operation returning column names and types, and its wording implies no side effects on the table. It doesn't detail output formatting, but that is a minor gap for a schema-listing tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with no filler. The primary function is stated first, followed by a concise usage directive. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter schema-inspection tool with no output schema, the description is complete: it states the return content, the target table, and the appropriate invocation point relative to querying. An agent has enough information to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline of 4 applies. The description adds useful context about which table is inspected and when the tool should be used, even though there are no parameters to explain.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it returns the name and type of each column in DWH.facturas. This clearly separates the tool from the sibling consultar_facturas, which is presumably for querying data rather than inspecting schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to use this tool first, before writing a query, when the table schema is unknown. It gives clear situational guidance, though it doesn't explicitly name the alternative tool or state when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.0
    • First observedconsultar_facturas
    • First observedlistar_columnas_facturas
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.6/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct roles: one is for inspecting the table schema, the other for executing read-only SQL queries against the table. There is no overlap or ambiguity about which to call.

Naming Consistency5/5

Both tool names follow the same lowercase snake_case verb_object pattern in Spanish: listar_columnas_facturas and consultar_facturas. The naming is predictable and aligns with each tool's function.

Tool Count4/5

With only two tools, the server is minimal, but the scope is intentionally narrow: schema discovery plus SQL querying of a single invoices table. This is slightly below the typical 3-15 tool range but reasonable and well-scoped for its purpose.

Completeness5/5

For a read-only query server over DWH.facturas, the surface is complete: agents can discover the schema and then run arbitrary SELECT queries to answer business questions. No obvious additional operations are needed for the stated purpose.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Microsoft SQL Server MCP

    NicolasPirello
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to connect and query Microsoft SQL Server databases using natural language, executing read-only SQL queries for safe data inspection and analysis.
    MIT

  • sqlserver-mcp

    moigomes
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables secure interaction with Microsoft SQL Server databases, allowing schema exploration, metadata retrieval, and read-only query execution through natural language.
    1
    -

  • mcp-sql-console

    ManojPabani
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables querying Microsoft SQL Server databases using natural language or predefined SQL, with read-only safety. Integrates with Cursor and Claude Desktop for database exploration and management.
    -