akahu-mcp

Akahu(뉴질랜드 오픈 뱅킹) 데이터를 Claude와 같은 LLM 에이전트에 노출하는 MCP 서버입니다. 에이전트가 사용자의 은행 계좌 목록을 확인하고, 투자 자산을 검토하며, 분석을 위해 거래 내역을 가져올 수 있도록 합니다.

로컬 SQLite 캐시(cache.db)는 최근 약 90일간의 거래 내역을 디스크에 보관하며 점진적으로 새로 고칩니다. 캐시 TTL은 Akahu Personal의 일일 업스트림 새로 고침 주기에 맞춰 24시간으로 설정되어 있습니다. 에이전트는 모든 도구에서 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 Personal Apps를 대상으로 구축 및 테스트되었으며, 이 앱은 업스트림 데이터를 하루에 한 번만 새로 고치므로 24시간 캐시 TTL을 사용합니다. 상용 플랜에서도 동일한 엔드포인트가 존재하지만, 상용 플랜의 경우 TTL을 단축하는 것이 좋을 수 있습니다.
legacy/에는 이 프로젝트의 기반이 된 두 개의 원본 스크립트(akahu.py, list_accounts.py)가 포함되어 있습니다. 이 스크립트들은 여전히 독립적으로 작동합니다. uv sync --group legacy로 의존성을 설치한 후 uv run --group legacy python legacy/list_accounts.py를 실행하세요.