akahu-mcp

一个将 Akahu（新西兰开放银行）数据暴露给 Claude 等 LLM 智能体的 MCP 服务器。它允许智能体列出你的银行账户、检查投资持仓并提取交易记录以进行分析。

本地 SQLite 缓存 (cache.db) 会在磁盘上保留最近约 90 天的交易记录并进行增量刷新。缓存 TTL 为 24 小时，以匹配 Akahu Personal 每天一次的上游刷新频率；智能体可以在任何工具上通过 force=True 来绕过缓存。

工具

list_accounts(force=False) — 银行/存款账户及其余额。不包含 Sharesight。
get_share_holdings(force=False) — Sharesight 投资组合：总价值、明细（回报/资本/货币/股息）以及各持仓行。
list_transactions(account, start=None, end=None, limit=100, force=False) — 从本地缓存中获取某个账户的交易记录，如果缓存超过 24 小时，则先从 Akahu 刷新。account 通过 ID 或模糊名称子字符串进行匹配。

设置

如果尚未安装，请安装 uv。
设置一个 Akahu 个人应用 (Personal App) — 这些是免费的单用户应用，你可以针对自己的 Akahu 账户创建。你将获得一个 app_token（个人应用的 ID）和一个属于你自己的 user_token。

在项目根目录创建一个 .env 文件：

AKAHU_USER_TOKEN=user_token_xxx
AKAHU_APP_TOKEN=app_token_xxx

运行 uv sync 安装依赖。
冒烟测试：uv run python -m akahu_mcp.sync — 应该会打印出你的账户并获取第一个账户的交易记录。

集成到 MCP 主机

Claude Code

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

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或你平台上的对应位置：

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

如果你的主机无法在 PATH 中找到 uv，请将 "uv" 替换为 which uv 命令返回的绝对路径。

注意事项

基于 Akahu 个人应用构建并测试，该应用每天仅刷新一次上游数据，因此缓存 TTL 设置为 24 小时。商业计划中也存在相同的端点，但在那种情况下可能值得缩短 TTL。
legacy/ 目录包含本项目最初的两个脚本 (akahu.py, list_accounts.py)。它们仍然可以独立运行 — 使用 uv sync --group legacy 安装它们的依赖，然后运行 uv run --group legacy python legacy/list_accounts.py。