wFirma MCP

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

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

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

すべての会社スコープのツールは、wfirma_list_companies が返す内部の companyId を必要とします。ポーランドの NIP は会社 ID として受け付けられません。

Related MCP server: InvoiceNinja MCP Server

読み取り専用の理由

このサーバーには、追加、編集、削除、送信、fiscalization、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