personal-finance-mcp

비공식. 이 프로젝트는 Plaid Inc.와 제휴, 보증 또는 후원 관계가 아닙니다. "Plaid"는 Plaid Inc.의 상표입니다. 이 프로젝트는 사용자가 제공한 자격 증명을 사용하여 Plaid API와 통신하는 자체 호스팅 클라이언트입니다.

은행, 신용카드, 대출 및 증권 계좌(Plaid 경유)를 Claude Code와 같은 MCP 클라이언트에 연결하는 자체 호스팅 읽기 전용 MCP 서버입니다. 제3자 애그리게이터(Monarch, Mint 등) 없이 평이한 영어로 자신의 재정 상태에 대해 질문하세요.

질문 예시

• "모든 계좌의 총 잔액은 얼마인가요?"

• "지난 30일 동안 100달러 이상 결제된 거래 내역을 보여줘."

• "내가 아직 결제 중인 구독 서비스는 무엇인가요?"

• "지난달 식료품비로 얼마를 썼나요?"

• "재인증이 필요한 은행이 있나요?"

세션 예시 (설명용):

you    : What did I spend on groceries last month?
claude : [calls get_transactions]
         $487.23 across 14 transactions. Top merchants:
         Whole Foods ($198), Trader Joe's ($156), Safeway ($89).

you    : Any subscriptions I'm still paying for?
claude : [calls get_recurring_transactions]
         7 active recurring outflows totaling $142/mo:
         Netflix ($15.99), Spotify ($11.99), NYT ($4), ...

도구

9가지 도구 모두 읽기 전용입니다. 각 도구는 {<data>: [...], "warnings": [...]}를 반환하므로, 특정 은행 연결에 문제가 생겨도 전체 쿼리가 중단되지 않습니다.

빠른 시작

Python 3.11+, Plaid 계정(무료 체험 플랜), MCP 클라이언트가 필요합니다.

1. Plaid 설정

1. https://dashboard.plaid.com/signup 에서 가입 → Trial 플랜(무료, 10개 항목)을 선택합니다.

2. Team Settings → Products: Transactions, Liabilities, Investments를 활성화합니다.

3. Team Settings → API: client_id와 프로덕션 secret을 복사합니다.

2. 설치

git clone https://github.com/<you>/personal-finance-mcp.git
cd personal-finance-mcp
python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # then fill in PLAID_CLIENT_ID and PLAID_SECRET
pytest -v              # sanity check

3. 각 은행 연결

연결하려는 은행마다 한 번씩 실행하세요:

uvicorn link_helper:app --port 8765

http://localhost:8765를 열고 Link a bank를 클릭하여 Plaid Link를 완료합니다. 터미널에 PLAID_TOKEN_CHASE=access-prod-xxx...와 같은 줄이 출력되면 이를 .env 파일에 붙여넣고 각 은행마다 반복합니다.

4. 실행

python server.py   # serves on http://localhost:8000/mcp

5. Claude Code에 추가

claude mcp add --transport http personal-finance http://localhost:8000/mcp

"list my accounts"라고 입력하여 확인해 보세요.

배포

어디서든 사용할 수 있는 배포 방법:

• Docker (포함됨): docker build -t personal-finance-mcp . && docker run --rm -p 8000:8000 --env-file .env personal-finance-mcp

• Python 호스트 (Fly.io, Railway, Raspberry Pi + Tailscale, VPS): .env.example에서 환경 변수를 설정하고, HTTPS를 통해 /mcp를 노출하며, 인증으로 보호합니다.

• Prefect Horizon (작성자가 사용하는 방식 — 고정 비용 $0): 전체 가이드는 docs/DEPLOYMENT.md를 참조하세요.

엔드포인트를 보호하세요. 토큰이 포함된 MCP 엔드포인트를 노출하면 연결된 모든 계좌 정보가 유출됩니다. OAuth 2.1, Cloudflare Access를 사용하거나 사설 네트워크에만 바인딩하세요.

보안

• 단일 테넌트. 1인당 1개 배포. 공유하지 마세요.

• 읽기 전용. 어떤 도구도 기관의 상태를 변경하지 않습니다. 변경하는 도구를 추가하지 마세요.

• 토큰은 환경 변수에만 존재하며 디스크에 저장되지 않습니다. .env는 gitignore 처리됩니다.

• Plaid 규정 준수 책임은 사용자에게 있습니다. 본인 계정 하의 Plaid 고객은 사용자 본인입니다.

배포 전 체크리스트:

• [ ] .env가 커밋되지 않았는지 확인: git log --all -- .env 결과가 없어야 함

• [ ] 기록에 실제 토큰이 없는지 확인: git log -S'access-prod-' --all 결과에 자리 표시자만 있어야 함

• [ ] MCP 엔드포인트 앞에 인증 게이트 설정 (또는 localhost 전용)

• [ ] 배포 환경에 HORIZON=1 (또는 유사한 설정)을 추가하여 link_helper.py 실행 차단

• [ ] 몇 주마다 get_institutions_status()를 확인하여 재인증 필요 여부 체크

문제 해결

실제 데이터가 있는데 도구가 빈 값을 반환함. 은행 연결 시 Plaid 제품이 활성화되지 않았기 때문입니다. Transactions + Liabilities + Investments를 활성화한 상태로 다시 연결하세요. 이 경우 도구는 warnings에 PRODUCTS_NOT_SUPPORTED를 표시합니다.

get_institutions_status()가 re_auth_required를 표시함. 은행의 Plaid 세션이 만료되었습니다. 업데이트 모드에서 link_helper.py를 실행하세요. 기존 액세스 토큰은 그대로 유지됩니다. docs/DEPLOYMENT.md를 참조하세요.

Plaid Link에서 은행이 "지원되지 않음"으로 표시됨 (Amex 등에서 흔함). 보통 INSTITUTION_REGISTRATION_REQUIRED 문제입니다. OAuth 은행은 먼저 Plaid 대시보드에서 기관별 등록이 필요합니다. docs/TROUBLESHOOTING.md를 참조하세요.

추가 문제: docs/TROUBLESHOOTING.md.

아키텍처

• server.py — FastMCP 서버, 9개의 읽기 전용 도구.

• plaid_client.py — Plaid SDK 래퍼: SecretStr 토큰 마스킹, 항목별 5분 상태 캐시, 응답 구조화, 구조화된 오류 매핑.

• link_helper.py — Plaid Link를 위한 로컬 전용 FastAPI 앱. HORIZON=1 설정 시 실행 거부.

심층 분석 (왜 /transactions/sync 대신 /transactions/get을 사용하는지 등): docs/ARCHITECTURE.md.

기여

CONTRIBUTING.md를 참조하세요. 범위는 의도적으로 읽기 전용, 단일 테넌트, Plaid 기반으로 제한되어 있습니다.