MainBook Bank Statement Converter

MCP · Claude, Claude Code, Cursor, Codex

Servidor MCP de Extractos Bancarios

Un servidor MCP financiero centrado en una única tarea: convertir extractos bancarios en PDF a JSON, Excel o CSV verificados — no es un MCP de contabilidad general. Se ejecuta localmente con tu clave de API de MainBook.

Crea una clave de API mainbook-mcp en PyPI →

~/Downloads — claude

Convierte ~/Downloads/march-statement.pdf y guarda el Excel junto a él.

mainbook - convert_bank_statement (MCP)(path: "~/Downloads/march-statement.pdf", output: "xlsx")

63 transacciones · 4 páginas · 4 créditos

Totales conciliados con el extracto

Guardado en ~/Downloads/march-statement.xlsx

+2 líneas (ctrl+o para expandir)

Listo — 63 transacciones. El saldo inicial de 4.127,50 y el final de 3.881,05 coinciden con el extracto, y no se marcó nada.

Configuración local con stdio

Añádelo a tu cliente

Elige la configuración del cliente, reemplaza el marcador de la clave y nombra solo las carpetas que el servidor puede usar.

Configuración del cliente verificada el 14 de agosto de 2026

MainBook MCP · configuración del cliente

Claude Desktop · Claude Code · Cursor · JSON

{
  "mcpServers": {
    "mainbook": {
      "command": "uvx",
      "args": ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"],
      "env": { "MAINBOOK_API_KEY": "mb_live_…" }
    }
  }
}

Codex · TOML

[mcp_servers.mainbook]
command = "uvx"
args = ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]

[mcp_servers.mainbook.env]
MAINBOOK_API_KEY = "mb_live_…"

Instala el paquete local

Instala uv, que incluye uvx

brew install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

O instala y actualiza con pip

pip install mainbook-mcp

pip install -U mainbook-mcp

• Ubicaciones del cliente Claude Desktop: Configuración → Desarrollador → Editar configuración. El mismo JSON funciona en Claude Code y Cursor.
• Límite de carpetas Pasa las carpetas en args, o define MAINBOOK_ALLOWED_DIRS. En esa variable de entorno, separa las rutas con dos puntos (:) en macOS/Linux y con punto y coma (;) en Windows.
• Runtime Python 3.11+; uvx obtiene el paquete sin ampliar el límite de carpetas.
• Alternativa con pip Usa mainbook-mcp como comando después de instalar con pip; actualiza el paquete con -U.

Herramientas y solicitudes

Cinco herramientas, cuatro solicitudes útiles

La paleta muestra la capacidad exacta; la transcripción de abajo muestra cómo una persona lo solicita.

mainbook · cinco herramientas y solicitudes de ejemplo

Paleta de herramientas

5 acciones explícitas · sin mutación de la cuenta

• convert_bank_statement
  Sube un PDF, crea e inicia un trabajo de conversión, consulta durante 30–900 segundos y devuelve JSON revisado en línea o escribe XLSX/CSV en el disco.
  Consume créditos de página
• get_conversion
  Comprueba un trabajo después de un tiempo de espera, devolviendo JSON en línea o escribiendo XLSX/CSV en un destino local elegido.
  Sin créditos · puede escribir un archivo
• list_conversions
  Devuelve una página de cursor de trabajos de la cuenta junto con su valor next_cursor.
  Acceso de solo lectura a la cuenta
• get_balance
  Devuelve el total, los créditos reservados y los disponibles, todos medidos en páginas de PDF.
  Acceso de solo lectura a la cuenta
• output_folder
  Lee o cambia la carpeta local predeterminada donde se escriben los resultados de conversión.
  Sin créditos · preferencia local

convert_bank_statement por sí solo crea un trabajo y consume créditos de página. Ninguna herramienta compra créditos, gestiona pagos, elimina trabajos ni cambia datos de la cuenta.

Pide en lenguaje natural

Cada solicitud de abajo se resuelve con una herramienta

• Convierte ~/Downloads/march-statement.pdf y guarda el Excel junto a él.
  usaconvert_bank_statement
• ¿Cuántas páginas de crédito me quedan?
  usaget_balance
• La última conversión expiró — comprueba el trabajo 8f14e45f… y dame el CSV.
  usaget_conversion
• Enumera mis conversiones recientes y dime cuáles volvieron con advertencias.
  usalist_conversions

Enrutamiento de resultados local

Dónde terminan tus archivos

El primer destino disponible gana. El servidor nunca reemplaza un archivo que ya existe.

MainBook · enrutamiento de resultados local

Prioridad 1output_path

Nombre de archivo absoluto o carpeta existente

Prioridad 2output_folder

Carpeta local recordada

Prioridad 3source folder

Mismo nombre base + extensión solicitada, junto al PDF

~/Downloadscarpeta permitida

march-statement.pdf

origen

march-statement.xlsx

guardado junto al PDF

march-statement (2).xlsx

nunca sobrescrito

luego (3), y así sucesivamente

JSON

en línea a menos que output_path esté definido

get_conversion necesita una carpeta explícita o recordada; nunca adivina la ubicación del PDF original.

Recordado en ~/.mainbook/preferences.json y compartido por los clientes locales; una carpeta faltante o no permitida se ignora y se informa del respaldo.

Límite local · créditos compartidos · trabajo asíncrono

Límites, créditos y tiempos

Una vista operativa cubre lo que el servidor puede tocar, qué consume una conversión, cuánto espera el cliente y el contrato público subyacente.

mainbook-mcp · límite local y API pública

Clave de API de toda la cuenta

Manténla privada y revócala en la aplicación si se expone. El servidor puede usar la cuenta, pero no tiene herramientas de pago ni de eliminación.

Solo carpetas nombradas

Las carpetas listadas son legibles y escribibles. Cualquier cosa fuera de ellas es rechazada por el servidor stdio local.

1 página = 1 crédito

Reservado por cada página de PDF.

20 páginas

Bono de registro de cuenta nueva, no un nivel MCP separado.

Monedero compartido

Los paquetes se compran en la aplicación web. El servidor MCP no puede comprar créditos.

Ventana de sondeo

30s mínimo900s máximo

No se publica una duración media. Si el cliente agota el tiempo, el trabajo del servidor continúa; llama a get_conversioncon el ID del trabajo o aumenta el tiempo de espera de la herramienta del cliente.

Límites operativos

500 páginas

máximo por PDF

50 MB

máximo por PDF

6 trabajos

en curso por clave de API

90 días

retención de documento + resultado

Debajo del servidor local se encuentra la API REST pública. Úsala directamente cuando estés construyendo tu propia integración en lugar de manejar un asistente.

Guía de API RESTJSON de OpenAPISwagger UI

Lee la descripción general de manejo en Seguridad. La cuenta debe aceptar los Términos de la API; de lo contrario, las llamadas fallan con api_terms_not_accepted. Las divulgaciones de datos aplicables están en la Política de Privacidad y la Divulgación de IA.

Las preguntas comunes

Preguntas frecuentes

¿Con qué clientes MCP funciona esto?

Funciona con Claude Desktop, Claude Code, Cursor y Codex usando los bloques de configuración de arriba.

¿Tengo que instalar algo?

uv/uvx obtiene y ejecuta el paquete mainbook-mcp publicado, o puedes ejecutar pip install mainbook-mcp. Se requiere Python 3.11 o posterior.

¿Puede el agente leer todo mi disco?

No. Solo puede leer o escribir dentro de las carpetas pasadas como argumentos o definidas mediante MAINBOOK_ALLOWED_DIRS; cualquier cosa fuera de ellas es rechazada.

¿Puede el agente gastar mi dinero?

convert_bank_statement consume créditos de página de tu cuenta; no existe ninguna herramienta para comprar créditos, hacer pagos ni eliminar nada.

¿Qué pasa si mi cliente deja de esperar?

El trabajo continúa ejecutándose en el servidor; llama a get_conversion con el ID del trabajo para retomarlo.

¿Hay un servidor alojado al que pueda apuntar?

El servidor se ejecuta localmente en tu máquina mediante stdio y se comunica con api.mainbook.ai desde allí.

Dale a tu asistente una herramienta útil

Crea la clave, nombra las carpetas y deja que el servidor local maneje el flujo de conversión.

Crea una clave de API mainbook-mcp en PyPI →Lee la guía de API REST →