{
  "markdown": "<!-- mcp-name: io.github.mutonby/aikount-mcp -->\n\n# Aikount MCP — Contabilidad española con IA para Claude, Cursor y ChatGPT\n\n> **Servidor MCP de contabilidad para autónomos y pymes en España.** Lleva tu\n> contabilidad a cualquier agente de IA: emite facturas, captura PDFs de gastos\n> por OCR, concilia movimientos bancarios y prepara el Modelo 303 — todo desde\n> Claude, Cursor, ChatGPT o cualquier cliente MCP.\n\n[![CI](https://github.com/mutonby/aikount-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mutonby/aikount-mcp/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/aikount-mcp.svg)](https://pypi.org/project/aikount-mcp/)\n[![Licencia: MIT](https://img.shields.io/badge/licencia-MIT-blue.svg)](LICENSE)\n\nAikount es un **SaaS de contabilidad agent-first**: una alternativa a Holded\npensada para que sea una **IA quien lleve la contabilidad**. Este repositorio es\nel **servidor [MCP](https://modelcontextprotocol.io) (Model Context Protocol)**\noficial que conecta tu agente de IA con tus libros a través de la API REST\npública de [Aikount](https://aikount.com). La API es el producto; la interfaz web\nes el plan B para humanos.\n\n> **¿Eres autónomo o gestoría y quieres que un agente de IA lleve tu\n> contabilidad en España?** Empieza en **[aikount.com](https://aikount.com)** y\n> conecta tu agente con este servidor MCP.\n\n## ¿Qué puedes hacer? (herramientas)\n\n| Herramienta | Qué hace |\n|-------------|----------|\n| `whoami` | Verifica el token y devuelve el tenant (empresa) activo |\n| `list_contacts` / `create_contact` | Clientes y proveedores |\n| `list_tax_types` | Tipos de IVA/IGIC/IPSI/IRPF y sus UUID para las líneas |\n| `list_products` | Catálogo de productos/servicios |\n| `list_invoices` / `get_invoice` | Consultar facturas de venta |\n| `create_invoice` / `issue_invoice` | Crear borrador y emitir (asigna número legal) |\n| `list_purchases` / `get_purchase` | Consultar gastos / facturas de compra |\n| `ingest_purchase_pdf` / `get_ingest_job` | OCR de un PDF a un gasto **sin duplicados** |\n| `list_treasuries` | Cuentas de banco / Stripe / PayPal con saldo |\n| `list_bank_movements` | Movimientos bancarios, con filtros |\n| `reconciliation_board` / `reconcile_movement` | Conciliación bancaria automática |\n| `list_accounts` / `ledger` / `trial_balance` | Plan General Contable (PGC), mayor y sumas y saldos |\n| `modelo_303_summary` / `modelo_303_csv` | IVA trimestral (Modelo 303) |\n| `api_request` | Acceso a cualquier otro endpoint (ver OpenAPI) |\n\n> **¿Por qué no hay `create_purchase`?** Las facturas de compra duplicadas\n> corrompen los totales de gasto, el IVA soportado y la conciliación bancaria.\n> Por eso los gastos solo se añaden vía `ingest_purchase_pdf`, que **deduplica\n> por identidad de factura**.\n\n## Instalación\n\nNecesitas una **API key** de Aikount (scope `*`, con prefijo `agl_`). La generas\ncon el botón **«Conectar agente»** dentro de la app web de Aikount — te muestra\nlas líneas `export` exactas.\n\n### Opción A — Hosted, sin instalar nada (MCP remoto)\n\nConecta tu cliente al endpoint hosted con tu token en la cabecera:\n\n```\nURL:    https://api.aikount.com/mcp        (streamable-HTTP)\nHeader: Authorization: Bearer agl_tu_token\n```\n\nEs multi-tenant: cada petición se autentica con su propio token. Ideal para\nclientes que soportan MCP remoto. Las mismas herramientas que la versión local.\n\n### Opción B — Local (este paquete)\n\n```bash\nexport AIKOUNT_TOKEN=\"agl_xxxxxxxxxxxxxxxxxxxxxxxx\"\n# opcional, por defecto producción:\n# export AIKOUNT_API=\"https://api.aikount.com/api/v1\"\n```\n\nEjecútalo con [uv](https://docs.astral.sh/uv/) (sin instalar nada):\n\n```bash\nuvx aikount-mcp\n```\n\nO con pip/pipx:\n\n```bash\npipx install aikount-mcp   # o: pip install aikount-mcp\naikount-mcp\n```\n\n### Claude Desktop / Claude Code\n\nAñádelo a tu configuración MCP (`claude_desktop_config.json`, o `.mcp.json` en\nClaude Code):\n\n```json\n{\n  \"mcpServers\": {\n    \"aikount\": {\n      \"command\": \"uvx\",\n      \"args\": [\"aikount-mcp\"],\n      \"env\": { \"AIKOUNT_TOKEN\": \"agl_xxxxxxxxxxxxxxxxxxxxxxxx\" }\n    }\n  }\n}\n```\n\n### Cursor\n\nAjustes → MCP → Add new server, con el mismo `command` / `args` / `env`.\n\n## Casos de uso\n\n- **«Emite una factura de 1.200 € a ACME por la consultoría de mayo.»** El agente\n  busca el contacto, resuelve el IVA y crea el borrador; tú confirmas y lo emite.\n- **«Mete este PDF de Amazon Web Services como gasto.»** OCR + alta deduplicada\n  del gasto en el Plan General Contable.\n- **«¿Cómo va mi IVA del segundo trimestre?»** Resumen del Modelo 303 al momento.\n- **«Concilia los movimientos del banco con las facturas.»** Conciliación\n  bancaria automática (auto-concilia con confianza ≥ 0,95).\n\n## Convenciones\n\n- **Dinero** en euros decimales (`unit_price: 1200.00`), no en céntimos. EUR\n  salvo que `currency` diga otra cosa.\n- **Fechas** ISO-8601 `AAAA-MM-DD`. **IDs** son UUID.\n- Las líneas referencian impuestos por `tax_type_id` (UUID de `list_tax_types`),\n  no por un código de texto. Omítelo para heredar el del contacto/producto.\n- Los errores vuelven como `{\"error\": true, \"status_code\": ..., \"detail\": ...,\n  \"hint\": ...}` para que el modelo se autocorrija (re-auth en 401, corregir el\n  cuerpo en 422).\n- El token tiene scope `*` — trátalo como una contraseña. El aislamiento por\n  empresa (multi-tenant) es automático.\n\nLa [especificación OpenAPI](https://api.aikount.com/openapi.json) es la fuente de\nla verdad para todo lo que este servidor no envuelve; accede a ella vía\n`api_request`.\n\n## Preguntas frecuentes (FAQ)\n\n### ¿Qué es Aikount MCP?\nEs un servidor MCP (Model Context Protocol) que conecta agentes de IA como\nClaude, Cursor o ChatGPT con tu contabilidad en Aikount, para que la IA pueda\n**emitir facturas, registrar gastos, conciliar el banco y preparar impuestos**\n(Modelo 303) usando el Plan General Contable español.\n\n### ¿Cómo conecto Claude (o Cursor/ChatGPT) con mi contabilidad?\nInstala el servidor con `uvx aikount-mcp`, genera tu API key en Aikount con\n«Conectar agente» y añade el bloque `mcpServers` a la configuración de tu cliente\nMCP. En segundos tu agente puede leer y escribir en tus libros.\n\n### ¿Es seguro? ¿Aikount guarda mis credenciales bancarias?\nNo. La conexión bancaria se hace mediante **pasarelas PSD2 reguladas** (Ponto\nConnect, Salt Edge, GoCardless); Aikount **nunca** almacena credenciales del\nbanco. Los datos se alojan en la **UE**. El token de la API es revocable y está\naislado por empresa.\n\n### ¿Sirve para autónomos y pymes en España?\nSí. Aikount está pensado para **autónomos y pymes españolas** y para las\n**gestorías** que las supervisan, con soporte multiempresa y multidivisa, Plan\nGeneral Contable y Veri\\*Factu. No sustituye a tu gestor: le entrega el trabajo\nhecho para revisar y firmar.\n\n### ¿Qué es el Modelo 303 y puede prepararlo la IA?\nEl **Modelo 303** es la autoliquidación trimestral del IVA en España. El agente\ngenera el resumen por trimestre (`modelo_303_summary`) y el detalle por\noperación (`modelo_303_csv`) listos para revisar y presentar.\n\n### ¿Es una alternativa a Holded?\nSí. Donde Holded es una suite por módulos, Aikount es un **agente de IA centrado\nen hacerte la contabilidad**, con precio por tramo de facturación. Comparativa:\n[aikount.com/alternativas-a-holded](https://aikount.com/alternativas-a-holded).\n\n## Sobre Aikount\n\nAikount — **contabilidad española agent-first** para autónomos, pymes y\ngestorías. Recursos:\n\n- 🌐 Web: **[aikount.com](https://aikount.com)**\n- 🤖 Contabilidad con IA: [aikount.com/contabilidad-con-ia](https://aikount.com/contabilidad-con-ia)\n- 🏦 Conciliación bancaria automática: [aikount.com/conciliacion-bancaria-automatica](https://aikount.com/conciliacion-bancaria-automatica)\n- 🧮 Calculadora de IVA trimestral (Modelo 303): [aikount.com/calculadora-iva-trimestral](https://aikount.com/calculadora-iva-trimestral)\n- 🆚 Alternativa a Holded: [aikount.com/alternativas-a-holded](https://aikount.com/alternativas-a-holded)\n- 📚 Documentación de la API: [api.aikount.com/docs](https://api.aikount.com/docs)\n- 🧩 Contexto para agentes: [aikount.com/llms.txt](https://aikount.com/llms.txt)\n\n## Desarrollo\n\n```bash\npython -m venv .venv && source .venv/bin/activate\npip install -e \".[dev]\"\npytest -q          # 23 tests, sin red (httpx MockTransport)\n```\n\nLos tests fijan cada herramienta a la ruta **real** de la API verificada contra\nla especificación OpenAPI en vivo, para que las rutas no se rompan en silencio.\n\n`server.json` es el manifiesto de este paquete para el\n[registro oficial de MCP](https://registry.modelcontextprotocol.io).\n\n## Licencia\n\nMIT — ver [LICENSE](LICENSE).\n",
  "bytes": 8575,
  "sha": "089d9319c624237beb7dafdd417e5669917600168b8e98f59e9bae34d923d8f4",
  "repo_slug": "mutonby/aikount-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mutonby_aikount_mcp_8db73aef/readme"
}