wFirma MCP

Неофициальный MCP-сервер только для чтения для API v2 wFirma (api2.wfirma.pl). Предоставляет совместимым с MCP AI-ассистентам типизированный доступ только для чтения к данным компании, счетам, контрагентам, расходам и платежам — с учётными данными, которые никогда не покидают вашу машину, и без коммерческого посредника между вами и wFirma.

Не связан с wFirma. "wFirma" является товарным знаком своего правообладателя.

Инструменты (9, все только для чтения)

Каждый инструмент уровня компании требует наличия внутреннего companyId, возвращаемого wfirma_list_companies. Польский NIP не принимается в качестве идентификатора компании.

Related MCP server: InvoiceNinja MCP Server

Почему только для чтения

Сервер намеренно не содержит операций добавления, редактирования, удаления, отправки, фискализации, KSeF или изменения платежей. Полный список исключённых категорий операций, сверенный с официальной документацией на doc.wfirma.pl, приведён в coverage-manifest.json. Если вам нужны операции записи, используйте собственный инструментарий wFirma, а не этот сервер.

Настройка

Учётные данные

Ключи API wFirma создаются в вашей панели 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. Клиент использует https из стандартной библиотеки Node.js с жёстким таймаутом в 20 секунд и защитой от превышения размера ответа.

• Таксономия ошибок по принципу fail-closed. Отсутствующие учётные данные, нечисловые идентификаторы компаний, слишком большие ответы и ошибки аутентификации — каждая из этих ситуаций вызывает отдельный код ошибки wfirma_* вместо общего сбоя.

• В логах нет PII. Параметры инструментов никогда не логируются.

• Манифест покрытия. coverage-manifest.json сопоставляет каждый инструмент с его endpoint, классом риска и проверяющим тестом; CI-тест гарантирует, что манифест остаётся синхронизированным с исходным кодом.

Лицензия

MIT