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: 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에서: 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의 무료 요금제는 비활성 상태 후 서비스를 "절전"시킵니다. 절전 후 첫 번째 요청은 응답하는 데 몇 초 정도 걸릴 수 있습니다.