akahu-mcp

Un servidor MCP que expone datos de Akahu (banca abierta de Nueva Zelanda) a agentes LLM como Claude. Permite al agente listar tus cuentas bancarias, inspeccionar tus participaciones de inversión y extraer transacciones para su análisis.

Una caché local de SQLite (cache.db) mantiene los últimos ~90 días de transacciones en el disco y se actualiza de forma incremental. El TTL de la caché es de 24 horas para coincidir con la actualización ascendente diaria de Akahu Personal; los agentes pueden pasar force=True en cualquier herramienta para omitirlo.

Herramientas

• list_accounts(force=False) — cuentas bancarias/de depósito con saldos. Sharesight está excluido.

• get_share_holdings(force=False) — cartera de Sharesight: valor total, desglose (rendimientos / capital / divisa / dividendos) y filas por participación.

• list_transactions(account, start=None, end=None, limit=100, force=False) — transacciones para una cuenta desde la caché local, actualizando desde Akahu primero si la caché tiene más de 24 horas. account coincide por ID o subcadena de nombre difusa.

Configuración

1. Instala uv si no lo tienes.

2. Configura una Aplicación Personal de Akahu: son aplicaciones gratuitas de usuario único que creas para tu propia cuenta de Akahu. Obtendrás un app_token (el ID de la aplicación personal) y un user_token para ti.

3. Crea un archivo .env en la raíz del proyecto:

   AKAHU_USER_TOKEN=user_token_xxx
   AKAHU_APP_TOKEN=app_token_xxx

4. uv sync para instalar las dependencias.

5. Prueba de funcionamiento: uv run python -m akahu_mcp.sync — debería imprimir tus cuentas y obtener transacciones para la primera.

Conexión a un host MCP

Claude Code

claude mcp add akahu --scope user -- uv --directory /absolute/path/to/akahu-mcp run akahu-mcp

Claude Desktop

Añádelo a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o el equivalente en tu plataforma:

{
  "mcpServers": {
    "akahu": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/akahu-mcp", "run", "akahu-mcp"]
    }
  }
}

Si tu host no puede encontrar uv en el PATH, reemplaza "uv" con la ruta absoluta obtenida mediante which uv.

Notas

• Construido y probado con Aplicaciones Personales de Akahu, que solo actualizan los datos ascendentes una vez al día, de ahí el TTL de caché de 24 horas. Los mismos endpoints existen en planes comerciales, pero podría valer la pena reducir los TTL en esos casos.

• legacy/ contiene los dos scripts originales (akahu.py, list_accounts.py) de los que surgió este proyecto. Todavía funcionan de forma independiente: instala sus dependencias con uv sync --group legacy, luego ejecuta uv run --group legacy python legacy/list_accounts.py.