bokio-mcp

Un servidor MCP para la API de contabilidad de Bokio. Expone 85 herramientas sobre una empresa de Bokio: facturas, clientes, proveedores, facturas de proveedores, asientos de diario, notas de crédito, plan contable, ejercicios fiscales, artículos, etiquetas, cargas, exportación SIE y pagos bancarios, de modo que un cliente MCP pueda leer y (opcionalmente) escribir tu contabilidad.

Sin cuentas, sin base de datos, sin servicio alojado. Una empresa por instancia de servidor.

"Which invoices are still unpaid?"
"Book the attached receipt against account 6570."
"Export the SIE file for the 2025 fiscal year."

Inicio rápido

Pruébalo con datos de prueba, sin necesidad de cuenta de Bokio:

BOKIO_MOCK=true npx bokio-mcp status
# { "companyName": "Testbolaget AB", "status": "active", ... }

BOKIO_MOCK=true sirve un Bokio falso en proceso, por lo que toda la superficie de herramientas funciona antes de tener credenciales.

Para datos reales, elige una de las dos rutas de credenciales a continuación y añade el servidor a tu cliente MCP.

Ruta A — token de integración privado (recomendado)

En Bokio: configuración de la empresa → Integraciones → Tokens de API → Crear integración privada. El token es de larga duración, está limitado a esa única empresa y no requiere revisión de OAuth.

{
  "mcpServers": {
    "bokio": {
      "command": "npx",
      "args": ["-y", "bokio-mcp"],
      "env": {
        "BOKIO_INTEGRATION_TOKEN": "your-token",
        "BOKIO_COMPANY_ID": "the-company-uuid-from-the-bokio-url"
      }
    }
  }
}

Ruta B — OAuth

Registra una integración en el portal de desarrolladores de Bokio con la URI de redirección http://127.0.0.1:7337/callback, luego:

export BOKIO_CLIENT_ID=... BOKIO_CLIENT_SECRET=...
npx bokio-mcp login

Eso abre Bokio en tu navegador y escribe los tokens en ~/.config/bokio-mcp/tokens.json (modo 0600). Los tokens de acceso se renuevan automáticamente, incluida la rotación del token de refresco. Apunta tu cliente MCP a npx -y bokio-mcp con las mismas dos variables de entorno configuradas.

Related MCP server: QuickBooks Online MCP Server

Las escrituras están desactivadas por defecto

Una instalación nueva puede leer pero no escribir. Las herramientas de mutación no solo están bloqueadas, sino que están ausentes de tools/list, por lo que el modelo nunca propone una edición que no pueda realizar:

BOKIO_ALLOW_WRITES=true

De las 85 herramientas, 38 son de solo lectura y 47 mutan. Inicia sin la bandera, confirma que el modelo está leyendo lo que esperas y luego activa las escrituras.

Comandos

Transporte HTTP

Para autoalojamiento, p. ej. detrás de un proxy inverso o en un contenedor:

MCP_AUTH_TOKEN=$(openssl rand -hex 32) bokio-mcp serve --http

/mcp queda entonces protegido por ese bearer estático. Sin MCP_AUTH_TOKEN, el servidor se vincula solo a 127.0.0.1 en lugar de exponer un puente no autenticado a datos contables en vivo. Se incluye un Dockerfile; por defecto usa este transporte.

Entorno

Consulta .env.example para la versión anotada.

Una nota sobre el almacenamiento de tokens

El archivo de tokens OAuth es texto plano en modo 0600 a menos que se establezca BOKIO_TOKEN_ENCRYPTION_KEY — la misma postura que las CLI de gh y aws. En una máquina personal, una clave almacenada junto a lo que cifra añade poco; configúrala cuando el archivo viva en un lugar menos privado, como una imagen de contenedor o un host compartido.

Desarrollo

npm install
npm test          # 36 tests, no database, no credentials
npm run typecheck
npm run dev       # tsx watch, stdio transport

BOKIO_MOCK=true enruta cada solicitud de Bokio a un mock en proceso en la capa fetch, por lo que se comporta de manera idéntica bajo stdio, bajo HTTP y dentro de pruebas sin servidor en ejecución. test/mcp.test.ts impulsa el protocolo MCP real de extremo a extremo contra él.

Las definiciones de herramientas están escritas a mano en src/tools/bokio/, pero la ruta y el método de cada una se verifican contra la especificación OpenAPI en tiempo de compilación mediante el helper op() — un error tipográfico en una ruta hace fallar la compilación. Regenera los tipos de la especificación con:

npm run gen:bokio

No soportado

• Más de una empresa por instancia. Las credenciales de Bokio son por empresa; ejecuta una segunda instancia para una segunda empresa.

• Ámbitos elevados. bank-payments:* requiere aprobación por integración de Bokio. Las herramientas de pago bancario están registradas pero fallarán hasta que tu integración sea aprobada y los ámbitos se añadan a BOKIO_SCOPES.

Licencia

MIT