robcerda/monarch-mcp-server

Monarch Money MCP Server

개요 – Monarch Money 개인 금융 API와 통신하고 Model Context Protocol(MCP)을 통해 데이터를 노출하는 소형 Python 서버입니다. MCP는 Claude Desktop, Claude Code 등 Anthropic 기반 AI 에이전트가 외부 도구를 호출하는 방식입니다. 이 서버를 실행하면 AI가 Monarch 계정, 거래, 예산, 태그 등을 읽고 수정할 수 있습니다.

중요한 이유 – Claude를 개인 비서(예: Claude Desktop, Claude Code, Meta Muse)로 사용하고 은행/예산 데이터에 직접 프로그래밍 방식으로 접근하려는 경우, 이 서버가 다리 역할을 합니다. Monarch의 복잡한 MFA/로그인 흐름을 처리하고 AI가 호출할 수 있는 명확한 명령 세트를 제공합니다.

주요 기능(README에 명시)

계정 관리 – 계정, 보유 자산 나열, 새로 고침 트리거.
거래 CRUD – 가져오기, 생성, 업데이트, 삭제, 일괄 분류, 태그 지정, 검토됨 표시.
카테고리 및 태그 처리 – 카테고리, 그룹, 태그 나열 새 태그 생성.
검색 및 필터 – 날짜, 금액, 판매자, 태그 등으로 강력한 거래 검색.
정기 예측 및 동기화된 청구서 – 예정된 정기 결제 및 부채 청구서 세부 정보 보기.
규칙 엔진 – 자동 분류 규칙 목록/생성/업데이트/삭제.
다중 전송 옵션 – 기본 stdio 기반 도구로 실행하거나 Streamable-HTTP 엔드포인트(/mcp)를 노출.
컨테이너 지원 – Astral의 uv/Python 3.12 슬림 기반 Docker 이미지, 인증된 세션을 위한 영구 볼륨 포함.
통합 노트 – Claude Desktop/Code, Meta Muse 및 MCP 호환 클라이언트와 함께 작동합니다.

빠른 시작(로컬)

클론 및 설치

git clone https://github.com/robcerda/monarch-mcp-server.git
cd monarch-mcp-server
uv sync --locked   # 또는 pip install -r requirements-lock.txt && pip install -e .

Claude 클라이언트 구성 – mcpServers 항목을 추가하여 uv run … monarch-mcp-server 명령을 가리킵니다(경로는 macOS와 Windows에서 다릅니다. 정확한 JSON은 README 참조).
한 번 인증
```
uv run python login_setup.py   # 또는 python login_setup.py
```
스크립트에서 다음을 수행할 수 있습니다:
- 브라우저 세션 쿠키 붙여넣기(권장 – Cloudflare CAPTCHA 회피).
- 이메일/비밀번호 + MFA로 로그인.
- 레거시 토큰 사용(있는 경우). 생성된 세션 토큰은 OS 키링(또는 Docker 컨테이너 내 파일)에 저장됩니다.
Claude 재시작 – AI가 get_accounts, get_transactions 등의 명령이 포함된 새 "Monarch Money" 도구를 인식합니다.

컨테이너 배포

빌드: docker build -t monarch-mcp-server .

인증(한 번) 영구 볼륨 사용:

docker run --rm -it -v monarch-session:/home/app/.monarch-mcp-server \
    monarch-mcp-server python login_setup.py

서버 실행(HTTP 모드, 기본 읽기 전용):

docker run -d --name monarch-mcp \
    -p 127.0.0.1:8000:8000 \
    -v monarch-session:/home/app/.monarch-mcp-server \
    monarch-mcp-server

클라이언트는 http://127.0.0.1:8000/mcp에 연결합니다.

쓰기 활성화(노출 시 위험): -e MONARCH_MCP_READ_ONLY=0 추가.
보안 팁 – 세션 볼륨에는 Linux 컨테이너에 암호화되지 않은 Monarch 토큰이 저장됩니다. 볼륨을 비밀로 취급하고 사용 후 삭제하세요.

보안 및 운영 참고 사항

단일 계정 서버 – 연결된 모든 클라이언트가 동일한 Monarch 세션을 공유합니다. 인증된 리버스 프록시 뒤에 두지 않는 한 HTTP 엔드포인트를 공개적으로 노출하지 마십시오.
호스트/출처 검사 – MONARCH_MCP_ALLOWED_HOSTS를 통해 특정 Host 헤더로 서버를 제한하여 DNS 리바인딩 공격을 완화할 수 있습니다.
기본 읽기 전용 – Docker 이미지는 읽기 전용 모드로 실행됩니다. 변경 명령(로그인/로그아웃 포함)은 MONARCH_MCP_READ_ONLY=0일 때만 등록됩니다.
자격 증명 저장 – 로컬 설치에서는 세션이 OS 키링에 저장됩니다. Docker에서는 일반 파일로 대체(Windows에서만 DPAPI로 암호화). 볼륨을 비공개로 유지하세요.
MFA 처리 – 로그인 스크립트는 TOTP 코드를 지원하며 Monarch가 요청하면 확인 코드를 묻습니다.

대상 사용자

Claude의 파워 유저 – AI 비서가 예산을 관리하고 지출을 분류하거나 요청 시 거래 데이터를 가져오길 원하는 분.
맞춤형 AI 에이전트를 개발하는 개발자 – 개인 금융 데이터를 위한 안정적인 MCP 호환 엔드포인트가 필요한 분.
명령줄/Docker 작업에 어느 정도 익숙하고 위에서 설명한 보안 모델을 신뢰하는 분 – 모든 사용자.

요약 – Monarch Money MCP Server는 표준 프로토콜을 통해 Claude 기반 AI 에이전트가 Monarch 금융 데이터와 상호 작용할 수 있도록 하는 특수 목적의 브리지로, 로컬 및 컨테이너화된 배포 옵션과 인증 및 보안에 대한 명확한 지침을 제공합니다.