wfirma-mcp

wFirma MCP

wFirma API v2（api2.wfirma.pl）向けの非公式な読み取り専用 MCP サーバーです。MCP 対応の AI アシスタントが、会社データ、請求書、取引先、経費、支払いに型付きで読み取り専用アクセスできます。認証情報がマシンの外に出ることはなく、wFirma との間に商用ミドルウェアもありません。

wFirma とは提携していません。「wFirma」はそれぞれの所有者の商標です。

ツール（9 個、すべて読み取り専用）

ツール	エンドポイント
wfirma_list_companies	GET /user_companies/find
wfirma_list_invoices	GET /invoices/find
wfirma_get_invoice	GET /invoices/get/{id}
wfirma_list_contractors	GET /contractors/find
wfirma_get_contractor	GET /contractors/get/{id}
wfirma_list_expenses	GET /expenses/find
wfirma_get_expense	GET /expenses/get/{id}
wfirma_list_payments	GET /payments/find
wfirma_get_payment	GET /payments/get/{id}

会社に紐づく各ツールには、wfirma_list_companies が返す内部の companyId が必要です。ポーランドの NIP は会社 ID として受け付けられません。

読み取り専用である理由

このサーバーには、追加、編集、削除、送信、税務処理、KSeF、支払い変更の操作は意図的に含まれていません。除外したカテゴリの全一覧は、公式ドキュメント（doc.wfirma.pl）と照合したうえで、coverage-manifest.json に記録されています。書き込みが必要な場合は、このサーバーではなく、wFirma 独自のツールをご利用ください。

セットアップ

認証情報

wFirma API キーは、wFirma のパネル（Integrations → API）で作成します。 必要な環境変数：

• WFIRMA_ACCESS_KEY
• WFIRMA_SECRET_KEY
• WFIRMA_APP_KEY

.env.example をご覧ください。実際の値は絶対にコミットしないでください。

ビルド

pnpm install
pnpm build      # → dist/index.js (self-contained esbuild bundle)
pnpm test       # all HTTP traffic is mocked; no live account needed

Claude Desktop／任意の stdio MCP クライアント

{
  "mcpServers": {
    "wfirma": {
      "command": "node",
      "args": ["/absolute/path/to/wfirma-mcp/dist/index.js"],
      "env": {
        "WFIRMA_ACCESS_KEY": "your-access-key",
        "WFIRMA_SECRET_KEY": "your-secret-key",
        "WFIRMA_APP_KEY": "your-app-key"
      }
    }
  }
}

Claude Code／Cursor（スコープ：プロジェクト）

claude mcp add wfirma -- node /absolute/path/to/wfirma-mcp/dist/index.js

設計上の注意点

• MCP SDK と zod 以外のランタイム依存関係はありません。 クライアントは Node の標準ライブラリ https を使用し、タイムアウトは 20 秒に固定、レスポンスサイズには上限を設けています。
• フェイルクローズ型のエラー分類。 認証情報の不足、数値以外の会社 ID、サイズ超過のレスポンス、認証エラーは、それぞれ汎用的なエラーではなく、個別の wfirma_* エラーコードを発生させます。
• ログに PII を含めません。 ツールのパラメーターはログに記録されません。
• カバレッジマニフェスト。 coverage-manifest.json では、各ツールをエンドポイント、リスククラス、それを検証するテストに対応付けています。CI テストにより、マニフェストとソースの同期が保たれていることを確認します。

ライセンス

MIT