wFirma MCP

Servidor MCP no oficial y de solo lectura para la API v2 de wFirma (api2.wfirma.pl). Proporciona a los asistentes de IA compatibles con MCP un acceso tipado y de solo lectura a los datos de empresa, facturas, contratistas, gastos y pagos, con credenciales que nunca salen de tu máquina y sin ningún middleware comercial entre tú y wFirma.

No está afiliado a wFirma. «wFirma» es una marca comercial de su respectivo propietario.

Herramientas (9, todas de solo lectura)

Cada herramienta con ámbito de empresa requiere el companyId interno devuelto por wfirma_list_companies. Un NIP polaco no se acepta como identificador de empresa.

Related MCP server: InvoiceNinja MCP Server

Por qué es de solo lectura

El servidor no incluye a propósito ninguna operación de alta, edición, eliminación, envío, fiscalización, KSeF o modificación de pagos. La lista completa de categorías excluidas, revisada contra la documentación oficial en doc.wfirma.pl, se recoge en coverage-manifest.json. Si necesitas operaciones de escritura, usa las herramientas propias de wFirma, no este servidor.

Configuración

Credenciales

Las claves de API de wFirma se crean en el panel de wFirma (Integraciones → API). Variables de entorno requeridas:

• WFIRMA_ACCESS_KEY

• WFIRMA_SECRET_KEY

• WFIRMA_APP_KEY

Consulta .env.example. Nunca hagas commit de valores reales.

Compilación

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

Claude Desktop / cualquier cliente MCP stdio

{
  "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 (ámbito: proyecto)

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

Notas de diseño

• Sin dependencias en tiempo de ejecución más allá del MCP SDK y zod. El cliente utiliza el https de la stdlib de Node con un tiempo de espera estricto de 20 s y una protección de tamaño de respuesta acotado.

• Taxonomía de errores fail-closed. Las credenciales ausentes, los identificadores de empresa no numéricos, las respuestas de tamaño excesivo y los fallos de autenticación generan cada uno un código de error wfirma_* distinto en lugar de un fallo genérico.

• Sin PII en los registros. Los parámetros de las herramientas nunca se registran.

• Manifiesto de cobertura. coverage-manifest.json mapea cada herramienta con su endpoint, clase de riesgo y la prueba que lo verifica; una prueba de CI garantiza que el manifiesto permanezca sincronizado con el código fuente.

Licencia

MIT