Metadata-Version: 2.4
Name: aikount-mcp
Version: 0.1.0
Summary: Servidor MCP de Aikount — contabilidad española con IA para autónomos y pymes. Emite facturas, registra gastos por OCR, concilia el banco y prepara el Modelo 303 de IVA desde Claude, Cursor o ChatGPT. Alternativa a Holded.
Project-URL: Homepage, https://aikount.com
Project-URL: Documentation, https://api.aikount.com/docs
Project-URL: OpenAPI spec, https://api.aikount.com/openapi.json
Author-email: Aikount <info@aikount.com>
Maintainer-email: Aikount <info@aikount.com>
License-Expression: MIT
License-File: LICENSE
Keywords: accounting,agente-ia,aikount,autonomos,chatgpt,claude,conciliacion-bancaria,contabilidad,contabilidad-con-ia,cursor,españa,factura-electronica,facturacion,gestoria,hacienda,holded-alternative,invoicing,iva,mcp,model-context-protocol,modelo-303,pymes,spain
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Natural Language :: Spanish
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# 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.

[![CI](https://github.com/mutonby/aikount-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mutonby/aikount-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/aikount-mcp.svg)](https://pypi.org/project/aikount-mcp/)
[![Licencia: MIT](https://img.shields.io/badge/licencia-MIT-blue.svg)](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.

```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).
