Cómo conectar Quaderno a Gemini vía MCP

💡 ¿Sin instalación? Usa cloud.anythingmcp.com directamente. Inicia sesión, pulsa Connectors → Quaderno, pega tus credenciales, genera una MCP API key y listo. Sin Docker, sin git clone, sin servidor local.

Quaderno + Gemini

Gestiona impuestos y facturas de Quaderno desde tu IA: calcula sales tax, IVA y GST para cualquier ubicación, valida números de IVA, busca contactos, facturas, notas de crédito, presupuestos, gastos y productos, emite y envía facturas por correo y solicita informes fiscales.

Requisitos previos

Las instrucciones de configuración completas están incluidas en el conector (visibles en el store al seleccionarlo). Las variables de entorno requeridas:

QUADERNO_ACCOUNT_NAME, QUADERNO_API_KEY

Paso 1 — Obtener credenciales

1. Inicia sesión en https://quadernoapp.com y abre Profile → API keys (https://quadernoapp.com/users/api-keys).
2. Copia la clave privada, que empieza por sk_, en QUADERNO_API_KEY. La clave publicable (pk_) no sirve aquí. La clave se envía como nombre de usuario de HTTP Basic con la contraseña vacía, solo a tu cuenta de Quaderno.
3. La misma página muestra tu URL de API, por ejemplo https://acme-1234.quadernoapp.com/api/. Pon la parte anterior a .quadernoapp.com (aquí acme-1234) en QUADERNO_ACCOUNT_NAME e instala el conector.
4. Comprueba la configuración con quaderno_ping: confirma la clave y muestra las peticiones que quedan en la ventana actual.

Las facturas se emiten y se envían solo tras tu sí: una factura emitida es un documento fiscal. Quaderno la numera de forma correlativa y no se puede borrar, solo anular o rectificar con una nota de crédito en la app de Quaderno. Antes de quaderno_create_invoice, la IA te muestra el cliente, las líneas, los precios y la moneda. Antes de quaderno_deliver_invoice, que envía la factura al cliente por correo al instante y no se puede deshacer, te dice qué factura va a qué dirección. quaderno_create_contact y quaderno_request_report también preguntan antes. Crear una factura no la envía. quaderno_delete_contact se instala desactivada.

Cálculo de impuestos: quaderno_calculate_tax devuelve el sales tax, el IVA o el GST de una venta a cualquier ubicación: nombre del impuesto, tipo, cuota, base y total, la jurisdicción hasta el nivel de ciudad y avisos como la inversión del sujeto pasivo para un número de IVA de la UE válido. Solo calcula y no registra nada. quaderno_validate_tax_id comprueba un número de IVA o de empresa en el registro oficial de su país (VIES de la UE, Reino Unido, Suiza, Quebec, Australia, Nueva Zelanda).

Qué lee: contactos, facturas, notas de crédito, presupuestos (Quaderno los llama proformas), gastos, productos, jurisdicciones fiscales y códigos fiscales. Los informes fiscales (impuestos recaudados por jurisdicción para tus declaraciones, una lista de facturas o una lista de notas de crédito) se generan en segundo plano: la IA solicita uno para un periodo, lo consulta hasta que está listo y te da el enlace de descarga.

Datos sensibles: las facturas y los contactos contienen nombres, direcciones y números fiscales de tus clientes, y son registros fiscales. Compártelos solo con quienes llevan la facturación.

Importes: los campos que terminan en _cents están en céntimos (12345 es 123,45); los precios y los resultados del cálculo de impuestos están en la unidad de la moneda.

Límite de peticiones: 100 llamadas cada 15 segundos. Un 429 significa esperar a que se reinicie la ventana.

Errores frecuentes: 401 Wrong API key or the user does not exist: la clave es incorrecta, es la clave pk_ o pertenece a otra cuenta distinta de QUADERNO_ACCOUNT_NAME. 406: un valor no válido, como un código fiscal desconocido. 422: el documento no se puede crear así, por ejemplo sin líneas.

No incluido: modificar, anular o marcar facturas como incobrables, registrar pagos, recibos, documentos recurrentes, transacciones, sesiones de checkout y cupones, evidencias, webhooks, el Sandbox y las cuentas de Quaderno Connect.

Paso 2 — Instalar el adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Paso 3 — Añadir el conector en Gemini

La URL de tu servidor: en AnythingMCP abre MCP Servers → el servidor donde está este conector y copia su URL (https://cloud.anythingmcp.com/mcp/…). Úsala donde esta guía muestra YOUR_SERVER_ID.

Gemini CLI lee los servidores MCP de ~/.gemini/settings.json (en Windows, %USERPROFILE%\.gemini\settings.json). Añade:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Crea una clave de API MCP en AnythingMCP en MCP Servers → tu servidor → API keys y pégala en lugar de YOUR_MCP_API_KEY.
2. Guarda el archivo y reinicia gemini.
3. Ejecuta /mcp dentro de Gemini CLI (o gemini mcp list en tu terminal): anythingmcp debería aparecer como conectado.
4. Empieza a escribir prompts: Gemini CLI ya puede llamar a las herramientas de Quaderno.

Herramientas disponibles

Ejemplos de prompts

• "¿Qué IVA se aplica a una suscripción SaaS de 49 EUR vendida a un particular en Lyon, Francia? ¿Y a una empresa de allí con un número de IVA válido?"
• "¿Es válido el número de IVA DE123456789?"
• "¿Qué facturas siguen pendientes o vencidas y cuánto suman por moneda?"
• "Emite una factura a Northwind GmbH por 10 horas de consultoría a 120 EUR la hora. Enséñamelo todo antes de crearla y no la envíes todavía."
• "Solicita un informe de resumen fiscal del tercer trimestre y dame el enlace de descarga cuando esté listo."

FAQ

¿Dónde busca Gemini CLI los servidores MCP? En ~/.gemini/settings.json para tu usuario, o en .gemini/settings.json dentro de un proyecto. gemini mcp list muestra cada servidor y si se conecta.

Siguientes pasos

• Página del conector
• Conectar a Claude
• Conectar a ChatGPT