Skip to main content
Glama
deenesjakoruzh
Andres2009

facturas-mcp

by Andres2009
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

facturas-mcp

DWH.facturas에 대해 Claude Desktop에 질문할 수 있는 읽기 전용 MCP 서버.

작동 방식

  • Claude Desktop이 이 서버를 로컬에서 실행합니다(별도 프로세스, stdio로 통신).

  • 서버는 읽기 전용 로그인(mcp_readonly)을 사용하여 SQL Server에 연결합니다. 이 로그인은 DWH.facturas에 대해 GRANT SELECT만 가지고 있습니다. 그 권한은 이 코드가 아니라 데이터베이스에 있습니다 -- 이것이 실제 보안 장벽입니다.

  • 두 가지 도구를 제공합니다:

    • listar_columnas_facturas: Claude가 SQL을 작성하기 전에 열을 파악할 수 있게 합니다.

    • consultar_facturas: DWH.facturas에 대해 읽기 전용 SELECT를 실행합니다.

Related MCP server: mcp-mssql

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에서: ALLOWED_TABLES 배열에 "DWH.OTRATABLA"를 추가하고, 선택적으로 기존과 동일한 listar_columnas_otratabla 도구도 추가하세요.

  3. npm run build를 실행하고 Claude Desktop을 다시 시작하세요.

원격 모드 (Render) -- 여러 사람이 Claude.ai에서 사용할 수 있도록

기본적으로 서버는 stdio 모드로 실행됩니다(로컬, 사용자당 하나의 프로세스, Claude Desktop이 실행). 여러 사람이 아무것도 설치하지 않고 Claude.ai에서 사용할 수 있게 하려면 Render에 HTTP 서비스로 배포하면 됩니다. 같은 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로 이동하여 인증 헤더 Authorization: Bearer <tu MCP_AUTH_TOKEN>와 함께 URL https://facturas-mcp.onrender.com/mcp를 등록하세요(정확한 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

  • mcp-mssql

    ismailcankaratas
    A
    license
    A
    quality
    D
    maintenance
    Enables natural language to SQL queries on MSSQL databases via Claude, with safe SELECT-only execution and schema discovery.
    3
    ISC

  • 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
    -