wFirma MCP

用于 wFirma API v2（api2.wfirma.pl）的非官方、只读 MCP 服务器。为兼容 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 秒超时和响应大小上限保护。

• 默认拒绝（fail-closed）的错误分类。 缺少凭据、非数字公司 ID、过大的响应以及认证失败，分别会引发不同的 wfirma_* 错误代码，而不是通用错误。

• 日志中不含 PII。 工具参数从不记录到日志。

• 覆盖清单。 coverage-manifest.json 将每个工具映射到其端点、风险类别和验证它的测试；CI 测试确保该清单与源代码保持同步。

许可证

MIT