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