SimpleFIN (read-only)
    → raw_syncs (append-only JSON)
    → truth tables (accounts, transactions, rules, budgets)
    → warm-cache aggregates
    → atomic functions / MCP tools (stdio + gRPC)

python -m venv .venv
# Windows: .venv\Scripts\activate
# Unix:    source .venv/bin/activate
pip install -e ".[dev]"
# optional gRPC transport (sibling ../GRPC-MCP)
pip install -e "../GRPC-MCP/python"
pip install -e ".[grpc]"

cp .env.example .env
# paste a Fernet key into FINANCE_ENCRYPTION_KEY
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

finance-mcp init                          # creates data/finance.db + a default profile
finance-mcp profile list                  # copy the profile UUID

finance-mcp claim-token --token "<setup-token>" --name "My Banks" --profile <PROFILE_UUID>
finance-mcp sync --profile <PROFILE_UUID>

finance-mcp serve-stdio                   # Claude Desktop / Cursor
finance-mcp serve-grpc --auth bearer      # sibling GRPC-MCP transport
finance-mcp token new --name cursor --profile <PROFILE_UUID>

from finance_mcp.config import Settings
from finance_mcp.core.db import Database
from finance_mcp import api

db = Database.from_settings(Settings.from_env())
print(api.net_worth(db, profile_id))

pytest -q

SimpleFIN (read-only)
    → raw_syncs (append-only JSON)
    → truth tables (accounts, transactions, rules, budgets)
    → warm-cache aggregates
    → atomic functions / MCP tools (stdio + gRPC)

# Finance Manager MCP

MCP 클라이언트를 위한 자체 호스팅 개인 금융 관리 도구입니다. 은행은 읽기 전용(SimpleFIN)으로 유지되며, 데이터는 사용자가 소유한 로컬 SQLite 파일에 저장됩니다. LLM은 결정적 집계만 조회할 수 있고 — 원장에는 절대 쓰지 않습니다.

GXP1

## 왜 이런 형태인가

* **멱등 수집 (Idempotent ingest)** — 거래는 은행이 부여한 SimpleFIN ID를 기준으로 키가됩니다. 동일한 덤프를 다시 동기화하면 새 항이 무에서 전혀 생기지 않으며, 동일하게 보이 는 신규 청구도 이 함되지 않습니다.
* **결정적 분류** — 첫 번째 일치하는 regex 규칙이 적용됩니다. 쓰기 경로에 모델이 없습니다.
* **예열된 캐시** — 월별 지출, 현금 흐름, 순자산 스냅샷, 반복 스트림 구조가 SQLite에 저장되어 재시작 시즉시 사용 준비가 됩니다. 캐시는 파생 데이터이며 `rebuild-cache`가 진원 테이블에서 다시 생성합니다.
* **프로필UUID 네임스페이스** — 모든 쓰기 도구는 `profile_id`를 요구합니다. 다중 프로필이 서로 누출되지 않습니다.
* **이중 전송** — Claude Desktop / Cursor를 위한 stdio, 함께 제공되는 [GRPC-MCP](../GRPC-MCP) 패키지를 통한 gRPC입니다.

## 설정

Python 3.11+.

GXP2

GXP3

### SimpleFIN 연결

MCP 클라이언트에서 은행에 연결하도록 요청하세요. 에이전트는 다음 단계를 수행해야 합니다:

1. `begin_simplefin_connect`를 호출합니다(또는 `connect_simplefin` 프롬프트 사용).
2. 브라우저에 [bridge.simplefin.org](https://bridge.simplefin.org)를 표시합니다. 사용자가 로그인하고, 은행(읽기 전용)을 연결하고, 일회성 설정 토큰을 복사합니다.
3. 이 토큰을 사용하여 `claim_connection`을 호출합니다. 액세스 URL은 획하여 저장됩니다.
4. 선택적으로 동일한 `profile_id`로 `sync_now`를 호출합니다.

터미널을 선호하면 CLI를 계속 사용할 수 있습니다:

GXP4

`sync`는 Task Scheduler / cron에서 실행해도 안전합니다. Overlapping windows가 겹쳐도 이중으로 계산하지 않습니다.

### 서버 실행

GXP5

Bearer 토큰은 한 번만 출력됩니다. gRPC는 SHA-256 해시만 저장합니다.

## 원자적 함수

`finance_mcp.api`의 모든 것은 일반 함수입니다. MCP 도구는 얇은 는다. 서버를 실 않고 라이브러리를 임포트할 수 있습니다:

GXP6

### 읽기

`list_accounts`, `get_balances`, ... (keep)

## 쓰기 (always require `profile_id`)

### Write는 항상.

## 테스트

테스트 스위트는 독립적입니다 — 합성 poke처만 사용, 자격 증명 없음.

GXP7

## Security

* SimpleFIN 액세스 URL은 `FINANCE_ENCRYPTION_KEY` (Fernet)로 암호화됩니다. 키를 백업하세요.
* gPRC bearer 토큰은 해시로 저장됩니다.
* 읽기 tools SQLite to `mode:ro`. 쓰기 tools 유일한 변경 경로이며 프로필로 범위가 제한됩니다.
* `data/l` 및 `.env`는 gitignore됩니다.

## License

개인 자유 호스팅 금융 관점에서 필요한 대로 사용할 수 있습니다.

But ensure not to use Korean punctuation weird.

Let's check the HTML: no.

Potential "Pocket".

Okay. Let's just output naturally.

One minor: "Warm cache" maybe could translate as "Warm cache" and keep the term. I'd say "예열된 캐시" is fine.

Also "from truth tables" -> "truth tables" is not a formal concept; "source tables" or "basic tables". The input says "truth tables" specifically. Could translate "기준 테이블" or "진리 테이블". I'd better say "실측 테이블 (truth tables)" maybe. But the instruction: Text inside inline code stays same, but "truth tables" is not code. Translate as "신 테이블" (source of truth). I used "진원 테이블" meaning "source table". That's acceptable.

Need to preserve "Deterministic categorization" in bold? Yes.

Let's produce final answer now.

But the assistant must output only translation, no code fence. So final message is the translated markdown itself.

Let's ensure there are no quotation wrapping. DoHere is the translation:

# Finance Manager MCP

MCP 클라이언트를 위한 자체 호스팅 개인 금융 관리 도구입니다. 은행 연결은 읽기 전용(SimpleFIN)으로 유지되며, 데이터는 사용자가 소유한 로컬 SQLite 파일에 저장됩니다. LLM은 결정적(deterministic) 합계만 조회할 수 있으며 — 원장에 절대 쓰지 않습니다.

GXP1

## 왜 이런 형태인가

* **멱등 수집** — 트랜잭션은 은행이 부여한 SimpleFIN ID를 기준으로 키가 지정됩니다. 동일한 덤프를 다시 동기화해도 새 행이 전혀 추가되지 않으며, 동일해 보이는 신규 거래도 병합되지 않습니다.
* **결정적 분류** — 첫 번째 일치가 우선하는 정규식 규칙입니다. 쓰기 경로에 모델이 없습니다.
* **예열된 캐** — 월간 지출, 현금 흐름, 순자산 스냅샷, 반복 스트림이 SQLite에 유지되어 재시자 시 즉시 준비됩니다. 캐시는 파생 데이터이며, `rebuild-cache`가 진원 테이블에서 다시 생성합니다.
* **프로필 UUID 네임스페이싱** — 모든 쓰기 도구는 `profile_id`를 요구합니다. 여러 프로필이 서로 누출되지 않습니다.
* **이중 전송** — Claude Desktop / Cursor용 stdio와 함께 제공되는 [GRPC-MCP](../GRPC-MCP) 패키지를 통한 gRPC입니다.

## 설정

Python 3.11+.

GXP2

GXP3

### SimpleFIN에 연결

MCP 클라이언트에서 은행에 연결을 요청하세요. 에이전트는 다음 단계를 수행해야 합니다:

1. `begin_simplefin_connect`를 호출합니다(또는 `connect_simplefin` 프롬터 사용).
2. 브라우저에 [bridge.simplefin.org](https://bridge.simplefin.org)를 표시하세요. 사용자가 로그인하고, 은행(읽기 전용)을 연결하고, 일회성 설정 토큰을 복사합니다.
3. 해당 토큰으로 `claim_connection`을 호출합니다. 접근 URL은 저장 시 암호화됩니다.
4. 선택적으로 같은 `profile_id`에 `sync_now`를 호출합니다.

터미널을 선호하면 CLI를 계속 사용할 수 있습니다:

GXP4

`sync`는 Task Scheduler / cron에서 실행해도 안전합니다. 겹치는 실행 창이 있어도 이중 계산되지 않습니다.

### 서버 실행

GXP5

Bearer 토큰은 한 번만 출력됩니다. gRPC는 SHA-256 해시만 저장합니다.

## 원자적 함수

`finance_mcp.api`의 모든 것은 일반 함수입니다. MCP 도구는 얇은 래퍼입니다. 서버를 실행하지 않고 라이브러리를 가져올 수 있습니다:

GXP6

### 읽기

`list_accounts`, `get_balances`, `net_worth`, `net_worth_history`, `search_transactions`, `recent_transactions`, `spending_by_categorie`, `cash_flow`, `recurring_streams`, `upcoming_payments`, `budget_status`, `list_rules`, `sync_status`, `profile_info`, `list_profiles`, `begin_simplefin_connect`

### 쓰기 (항상 `profile_id` 필요)

`claim_connection`, `create_rule`, `update_rule`, `delete_rule`, `apply_rules`, `create_budget`, `update_budget`, `delete_budget`, `sync_now`

## 테스트

테스트 스위트는 독립적입니다 — 합성 스처만 사용하며 자격 증명이 없습니다.

GXP7

## 보안

* SimpleFIN 접근 URL은 `FINANCE_ENCRYPTION_KEY`(Fernet)로 암호화됩니다. 키를 백업하세요.
* gRPC bearer token은 해시로 저장됩니다.
* 읽기 도구는 SQLite를 `mode=ro`로 열니다. 쓰기 도구는 유일한 변적 경로이며 profile에 범위가 한정됩니다.
* `data/` 및 `.env`는 gitignore 대상입니다.

## License

개인 자호 금융 관리를 위해 원하는 대로 사용하세요.