Avie Money Lover MCP / Local Bridge

Integración no oficial de Money Lover para dos flujos de trabajo:

1. Servidor MCP — exponer herramientas de lectura/escritura de Money Lover a un cliente compatible con MCP.

2. GPT + puente local — permitir que ChatGPT prepare/revise el JSON del extracto mientras tu propia máquina conserva el token/cookie de Money Lover y realiza la importación final.

Proyecto no oficial. Este repositorio no está afiliado, respaldado ni patrocinado por Money Lover. Utiliza endpoints web observados en la aplicación web de Money Lover. Esos endpoints, los flujos de autenticación, el comportamiento de las categorías y los requisitos anti-bot pueden cambiar sin previo aviso.

Qué puede hacer

• Leer información del usuario autenticado

• Listar carteras y categorías de carteras

• Leer transacciones por rango de fechas

• Resolver los ID de origen user_category_v2 de Money Lover a ID de tiempo de ejecución usando el historial de transacciones

• Vista previa de una sola transacción sin escribir

• Añadir una transacción con protección contra duplicados

• Vista previa de un lote de extracto bancario/de tarjeta

• Conciliar gastos − ingresos contra el total del extracto

• Marcar duplicados exactos, duplicados probables, categorías sin resolver y filas de revisión

• Importar secuencialmente solo tras confirmación explícita

• Verificar las transacciones creadas leyéndolas de nuevo

• Re-ejecutar de forma segura tras una importación parcial: los duplicados exactos se omiten

Related MCP server: monarch-mcp

Requisitos

• Windows 10/11, macOS o Linux

• Node.js 22+

• Una cuenta de Money Lover que controles

• Para escrituras fiables: una sesión wallet-owner reciente, cookie de navegador/cf_clearance actual si es necesario, y el User-Agent de navegador correspondiente

Inicio rápido

git clone https://github.com/haonguyen97ftu/avie-moneylover-mcp.git
cd avie-moneylover-mcp
npm install
npm test

Configuración del asistente de Windows

scripts\setup-windows.cmd

Establece las credenciales solo en el shell actual:

set "MONEYLOVER_ACCESS_TOKEN=YOUR_FRESH_OWNER_TOKEN"
set "MONEYLOVER_CF_CLEARANCE=YOUR_CURRENT_CF_CLEARANCE_VALUE"
set "MONEYLOVER_USER_AGENT=YOUR_EXACT_BROWSER_USER_AGENT"

Luego ejecuta:

scripts\doctor.cmd

Flujo de trabajo recomendado GPT + local

Bank/card statement
        ↓
ChatGPT extracts + categorizes
        ↓
statement JSON
        ↓
local preview
        ↓
review / duplicate / reconciliation checks
        ↓
explicit IMPORT confirmation
        ↓
Money Lover
        ↓
local verification report

No pegues tokens de Money Lover, tokens de refresco, contraseñas, cookies de navegador ni cf_clearance en ChatGPT, issues de GitHub, registros o capturas de pantalla. ChatGPT solo necesita el extracto más el JSON de vista previa/resultado generado.

Vista previa de un extracto

scripts\preview.cmd data\your-statement.json

Importar tras la revisión

scripts\import.cmd data\your-statement.json

El importador requiere que escribas exactamente:

IMPORT

antes de que comiencen las escrituras.

Consulta docs/HUONG_DAN_SU_DUNG.md para la guía completa en vietnamita.

Comportamiento de API observado

Las solicitudes autenticadas actualmente usan:

Authorization: AuthJWT <access_token>

Endpoints observados:

Las escrituras pueden requerir cabeceras similares a las de un navegador y una sesión de Cloudflare actual. Las variables de entorno compatibles incluyen:

• MONEYLOVER_ACCESS_TOKEN

• MONEYLOVER_CF_CLEARANCE

• MONEYLOVER_COOKIE

• MONEYLOVER_USER_AGENT

• MONEYLOVER_TIMEOUT_MS

• MONEYLOVER_CATEGORY_LOOKBACK_DAYS

• MONEYLOVER_WRITE_DELAY_MS

Formato de extracto por lotes

Empieza desde data/example-statement.json. La documentación completa de campos está en docs/STATEMENT_FORMAT.md.

Vista previa:

npm run preview -- data\your-statement.json

Importar:

npm run import -- data\your-statement.json

Banderas opcionales:

• --allow-review — incluir filas dejadas intencionadamente en review después de inspeccionarlas

• --allow-mismatch — omitir la protección de conciliación del extracto; úsalo solo cuando entiendas la discrepancia

• --allow-shared-wallet — omitir la comprobación de seguridad del propietario; las escrituras en carteras compartidas pueden fallar igualmente

• --confirm IMPORT — confirmación no interactiva; no recomendado para uso manual habitual

Valores de seguridad predeterminados

El importador se niega a escribir cuando:

• cualquier fila está blocked

• existe una fila review a menos que se proporcione --allow-review

• la diferencia de conciliación del extracto no es cero a menos que se proporcione --allow-mismatch

• el usuario autenticado no es el propietario de la cartera a menos que se proporcione --allow-shared-wallet

• la confirmación no es exactamente IMPORT

Los importes deben ser números positivos.

Categoría v2

Algunas cuentas exponen un ID de categoría fuente/plantilla desde /category/list, mientras que /transaction/add espera un ID de categoría de tiempo de ejecución diferente. El puente aprende este mapeo de las transacciones existentes.

Si una categoría nunca ha aparecido en el historial, copia:

config/runtime-category-overrides.example.json

a:

config/runtime-category-overrides.json

y añade el ID de tiempo de ejecución observado en una solicitud de transacción real del navegador. Git ignora el archivo de anulación local.

Seguridad del repositorio público

El repositorio está configurado para evitar confirmar datos financieros locales por defecto:

• data/*.json se ignora excepto el ejemplo saneado

• out/ se ignora

• .env* se ignora

• las anulaciones locales de categorías de tiempo de ejecución se ignoran

• los archivos auxiliares de sesión local se ignoran

Antes de hacer push, ejecuta:

npm run repo:check
npm test

Luego inspecciona git status manualmente.

Seguridad

Si un token, contraseña, token de refresco, cookie de navegador o valor de cf_clearance se expone alguna vez, trátalo como comprometido y rota/revoca la sesión. Consulta SECURITY.md.

Contribuciones

Los informes de errores y las pull requests son bienvenidos. Por favor, lee CONTRIBUTING.md antes de enviar cambios. Nunca incluyas extractos financieros reales, identificadores de cuenta, tokens o cookies en issues o fixtures de prueba.

Documentación

• Guía de uso en vietnamita

• Formato JSON del extracto

• Arquitectura

• Guía de publicación en GitHub

• Política de seguridad

• Registro de cambios

• Prompt de normalización de extractos para GPT

• Prompt de revisión de vista previa para GPT

Licencia

MIT — consulta LICENSE.