facturas-mcp

Read-only-MCP-Server, um Claude Desktop zu DWH.facturas zu befragen.

So funktioniert es

• Claude Desktop startet diesen Server lokal (eigener Prozess, Kommunikation über stdio).

• Der Server verbindet sich mit SQL Server über einen Read-only-Login (mcp_readonly), der ausschließlich GRANT SELECT auf DWH.facturas besitzt. Diese Berechtigung lebt in der Datenbank, nicht in diesem Code -- sie ist die eigentliche Sicherheitsbarriere.

• Er stellt zwei Tools bereit:

  • listar_columnas_facturas: damit Claude die Spalten entdeckt, bevor es SQL schreibt.

  • consultar_facturas: führt ein schreibgeschütztes SELECT gegen DWH.facturas aus.

Related MCP server: MSSQL Database MCP Server

Schritt 1 -- Den eingeschränkten Login in SQL Server erstellen

Führe setup-db-login.sql EINMAL mit einem Benutzer aus, der Administratorrechte für die Datenbank besitzt. Ändere das Beispielpasswort, bevor du es ausführst.

Schritt 2 -- Die Zugangsdaten dieses Servers konfigurieren

Erstelle in diesem Ordner eine Datei .env (sie wird nicht nach Git hochgeladen) mit:

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

Schritt 3 -- Den Server in Claude Desktop registrieren

Öffne claude_desktop_config.json (unter Windows: %APPDATA%\Claude\claude_desktop_config.json) und füge Folgendes innerhalb von "mcpServers" hinzu:

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

Schließe Claude Desktop vollständig und öffne es erneut, damit der neue Server geladen wird.

Schritt 4 -- Es testen

Frage Claude Desktop zum Beispiel: „Wie viel habe ich heute laut DWH.facturas verkauft?“

Später eine weitere Tabelle hinzufügen

1. In SQL Server: GRANT SELECT ON DWH.otratabla TO mcp_readonly;

2. Füge in src/index.ts "DWH.OTRATABLA" zum Array ALLOWED_TABLES hinzu und optional ein Tool listar_columnas_otratabla, das dem bereits vorhandenen entspricht.

3. npm run build und starte Claude Desktop neu.

Remote-Modus (Render) -- damit mehrere Personen es über Claude.ai nutzen können

Standardmäßig läuft der Server im stdio-Modus (lokal, ein Prozess pro Benutzer, von Claude Desktop gestartet). Damit mehrere Personen es ohne Installation von Claude.ai aus nutzen können, kann er als HTTP-Dienst in Render bereitgestellt werden. Dasselbe dist/index.js dient für beide Modi -- der Schalter ist die Umgebungsvariable MCP_TRANSPORT.

Wichtig: Im HTTP-Modus bleibt der einzige Schutz der Datenbank der Read-only-Login, aber der MCP-Server selbst ist über eine öffentliche URL erreichbar. Deshalb erfordert der HTTP-Modus ein Token (MCP_AUTH_TOKEN) -- ohne es startet der Prozess nicht einmal. Jeder, der die URL und das Token besitzt, kann SELECT gegen DWH.facturas ausführen. Behandle dieses Token also wie ein Passwort: veröffentliche es nicht, lade es nicht nach Git hoch und rotiere es, falls es durchsickert.

Schritt 1 -- Ein sicheres Token erzeugen

Zum Beispiel mit PowerShell:

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

Bewahre diesen Wert auf -- er ist dein MCP_AUTH_TOKEN.

Schritt 2 -- Den Web Service in Render erstellen

1. Lade dieses Projekt in ein GitHub-Repository hoch (node_modules und dist müssen außerhalb des Repos bleiben -- sie stehen bereits in .gitignore -- Render führt npm install und npm run build selbst aus).

2. Bei Render: New -> Web Service, verbinde das Repo.

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

4. Start Command: npm start

5. Environment variables (Registerkarte 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 setzt PORT automatisch -- es muss nicht hinzugefügt werden.)

6. Deploy. Wenn der Vorgang abgeschlossen ist, gibt Render dir eine URL wie https://facturas-mcp.onrender.com.

Schritt 3 -- Testen, ob der Server antwortet

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"}}}'

Wenn er mit serverInfo und capabilities antwortet, ist der Server aktiv und akzeptiert das Token. Ohne den richtigen Authorization-Header muss er mit 401 antworten.

Schritt 4 -- Verbindung über Claude.ai / Claude Desktop herstellen

In Claude.ai (oder einer aktuellen Version von Claude Desktop): Settings -> Connectors -> Add custom connector, und registriere die URL https://facturas-mcp.onrender.com/mcp mit dem Authentifizierungs-Header Authorization: Bearer <tu MCP_AUTH_TOKEN> (die genaue Oberfläche kann je nach Claude-Version variieren -- suche nach der Option für Remote-MCP-Server / custom connector).

Hinweis: Der kostenlose Render-Plan versetzt den Dienst nach Inaktivität in den Schlafmodus -- die erste Anfrage nach dem Aufwachen kann ein paar Sekunden dauern.