{
  "markdown": "# wFirma MCP\n\nUnofficial, read-only MCP server for the [wFirma](https://wfirma.pl/) API v2\n(`api2.wfirma.pl`). Gives MCP-compatible AI assistants typed, read-only access\nto company data, invoices, contractors, expenses, and payments — with\ncredentials that never leave your machine and no commercial middleware between\nyou and wFirma.\n\nNot affiliated with wFirma. \"wFirma\" is a trademark of its respective owner.\n\n## Tools (9, all read-only)\n\n| Tool | Endpoint |\n|---|---|\n| `wfirma_list_companies` | `GET /user_companies/find` |\n| `wfirma_list_invoices` | `GET /invoices/find` |\n| `wfirma_get_invoice` | `GET /invoices/get/{id}` |\n| `wfirma_list_contractors` | `GET /contractors/find` |\n| `wfirma_get_contractor` | `GET /contractors/get/{id}` |\n| `wfirma_list_expenses` | `GET /expenses/find` |\n| `wfirma_get_expense` | `GET /expenses/get/{id}` |\n| `wfirma_list_payments` | `GET /payments/find` |\n| `wfirma_get_payment` | `GET /payments/get/{id}` |\n\nEvery company-scoped tool requires the internal `companyId` returned by\n`wfirma_list_companies`. A Polish NIP is **not** accepted as a company id.\n\n## Why read-only\n\nThe server intentionally contains no add, edit, delete, send, fiscalization,\nKSeF, or payment-mutation operation. The full list of excluded categories,\nreviewed against the official documentation at\n[doc.wfirma.pl](https://doc.wfirma.pl/), is recorded in\n[`coverage-manifest.json`](coverage-manifest.json). If you need writes, use\nwFirma's own tooling — not this server.\n\n## Setup\n\n### Credentials\n\nwFirma API keys are created in your wFirma panel (Integrations → API).\nRequired environment variables:\n\n- `WFIRMA_ACCESS_KEY`\n- `WFIRMA_SECRET_KEY`\n- `WFIRMA_APP_KEY`\n\nSee [`.env.example`](.env.example). Never commit real values.\n\n### Build\n\n```bash\npnpm install\npnpm build      # → dist/index.js (self-contained esbuild bundle)\npnpm test       # all HTTP traffic is mocked; no live account needed\n```\n\n### Claude Desktop / any stdio MCP client\n\n```json\n{\n  \"mcpServers\": {\n    \"wfirma\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/wfirma-mcp/dist/index.js\"],\n      \"env\": {\n        \"WFIRMA_ACCESS_KEY\": \"your-access-key\",\n        \"WFIRMA_SECRET_KEY\": \"your-secret-key\",\n        \"WFIRMA_APP_KEY\": \"your-app-key\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code / Cursor (scope: project)\n\n```bash\nclaude mcp add wfirma -- node /absolute/path/to/wfirma-mcp/dist/index.js\n```\n\n## Design notes\n\n- **No runtime dependencies beyond the MCP SDK and zod.** The client uses\n  Node's stdlib `https` with a hard 20s timeout and a bounded response-size\n  guard.\n- **Fail-closed error taxonomy.** Missing credentials, non-numeric company\n  ids, oversized responses, and auth failures each raise a distinct\n  `wfirma_*` error code instead of a generic failure.\n- **No PII in logs.** Tool parameters are never logged.\n- **Coverage manifest.** `coverage-manifest.json` maps every tool to its\n  endpoint, risk class, and the test that proves it; a CI test enforces the\n  manifest stays in sync with the source.\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 3047,
  "sha": "edf62d51c6d853d91c6d9de97d13f5e210bf4fc7d9ce30e3c36d85ca06274ebf",
  "repo_slug": "agente-dev/wfirma-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_agente_dev_wfirma_mcp_d56b4734/readme"
}