facturas-mcp

DWH.facturas について Claude Desktop に質問するための読み取り専用 MCP サーバー。

仕組み

• Claude Desktop がこのサーバーをローカルで起動する（専用プロセス、stdio で通信）。

• サーバーは 読み取り専用 のログイン（mcp_readonly）を使って SQL Server に接続する。 このログインには DWH.facturas に対する GRANT SELECT しかない。その権限はデータベース 側にあり、このコードにはない -- これが実際のセキュリティの壁である。

• 2 つのツールを公開する:

  • 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 モードで動作する（ローカル、ユーザーごとに 1 プロセス、 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 を選択し、URL https://facturas-mcp.onrender.com/mcp を認証ヘッダー Authorization: Bearer <tu MCP_AUTH_TOKEN> 付きで登録する（正確な UI は Claude のバージョンに よって異なる場合がある -- リモート MCP サーバー / カスタムコネクタのオプションを探すこと）。

注: Render の free プランは、非アクティブになるとサービスを「スリープ」させる -- スリープ後の最初の リクエストは応答まで数秒かかることがある。