monarch-mcp2-obot

obot 뒤에서 자체 호스팅하기 위한 단일 테넌트 Monarch Money MCP 서버로, erikrubstein/monarch-mcp2에서 포크되었습니다. (흔히 볼 수 있는 robcerda/monarch-mcp-server 계열의 포크가 아니라, 자체 API 클라이언트인 monarch-api2를 기반으로 한 독립적인 구현체입니다.)

이 포크는 업스트림이 다루지 않았던 세 가지 이유로 존재합니다:

1. MCP Python SDK v2로 포팅됨 (MCPServer이며, 더 이상 사용되지 않는 v1 FastMCP가 아님).

2. obot에 맞춰 설계된 로그인 워크플로: 자격 증명을 환경 변수로 한 번만 구성하면 되고, 선택적 TOTP 시드 지원으로 인증기 앱 MFA 챌린지를 자동으로 해결할 수 있습니다. 브라우저도, OS 키링도, 6자리 코드를 수동으로 복사할 필요도 없습니다.

3. 의도적으로 단일 테넌트: 실행 중인 인스턴스당 정확히 하나의 Monarch 계정만 사용합니다. 클라이언트가 보내려고 해도 어떤 도구 호출도 다른 계정의 세션을 대상으로 할 수 없습니다. 아래의 "의도적인 단일 테넌트"를 참조하세요.

Monarch Money와 제휴하지 않았으며, Monarch Money의 보증이나 지원을 받지 않습니다.

업스트림에서 상속된 것

14개 그룹에 걸친 125개 도구 — 계정, 거래, 예산, 현금흐름, 카테고리, 목표, 가계, 투자, 판매처, 영수증, 반복, 보고서, 태그 — 가 monarch-mcp2에서 변경 없이 유지됩니다. 어떤 내용이 포함되고 무엇이 의도적으로 범위를 벗어나는지(거래 규칙 및 자동화, 제공자 계정 연결 흐름, 계정 관리 경계)는 도구 목록과 설계 노트를 참조하세요.

Related MCP server: monarch-mcp

여기서 달라진 점

인증: auth_login, auth_status

업스트림의 auth_create_session / auth_save_session / auth_load_session(완전 수동 1회성 로그인용으로 여전히 동작) 위에 추가된 두 가지 새 도구:

• auth_login — 서버 환경에 MONARCH_EMAIL / MONARCH_PASSWORD(그리고 인증기 앱 MFA의 경우 MONARCH_TOTP_SECRET)가 구성되어 있으면 인수가 필요 없습니다. 시드에서 현재 코드를 계산해 MFA 챌린지를 자동으로 처리합니다. 서버 구성을 건드리지 않고 1회성 로그인을 하려면 email / password / totp_secret / mfa_code를 명시적으로 전달하면 됩니다.

• auth_status — 세션이 존재하고 현재 유효한지 보고합니다(기본적으로 가벼운 API 호출 1회). 세션 토큰을 절대 반환하지 않습니다.

서버는 자격 증명이 구성된 경우 시작 시 이 로그인을 자동으로 시도합니다. 최선 노력(best-effort) 방식이며 치명적이지 않아서, 잘못된 비밀번호나 네트워크 장애가 있어도 서버 시작을 막지 않습니다. auth_status와 auth_login은 진단과 재시도에 계속 사용할 수 있습니다.

TOTP 시드: 인증기 앱에 등록할 때 사용하는 것과 동일한 base32 비밀키입니다(QR 코드로 스캔하는 값). Monarch는 인증기 앱 MFA를 활성화할 때 이 값을 한 번만 보여줍니다. 그때 저장해 두세요. 그렇지 않으면 새 시드를 얻기 위해 MFA를 비활성화했다가 다시 활성화해야 합니다. 이는 계정의 MFA 방식이 인증기 앱인 경우에만 적용됩니다. 이메일 코드 MFA는 이런 방식으로 자동화할 수 없으며(코드를 계산할 시드가 없음), auth_login의 mfa_code 인수를 통해 사람이 새 코드를 전달해 주어야 합니다.

의도적인 단일 테넌트

session_path는 모든 기본 함수에 존재하지만(monarch-api2 규칙) MCP 클라이언트에 노출되기 전에 모든 도구의 공개 스키마에서 제거됩니다 — tool_metadata.py 참조. 하나의 배포, 하나의 Monarch 계정, 하나의 세션 파일이며 MONARCH_SESSION_PATH / MONARCH_CONFIG_DIR로 한 번만 선택합니다. 이는 단순한 구성 기본값이 아닙니다. 설계상 어떤 도구 호출도 요청별로 이 값을 재정의할 수 없으며, 클라이언트가 값을 보내더라도 무시됩니다(tests/test_server.py::test_tool_call_ignores_session_path_even_if_a_client_sends_it 참조).

obot의 두 배포 모델을 위한 전송 선택

obot은 여기와 관련된 두 가지 방식으로 MCP 서버를 지원합니다. 명령어/uvx 기반(stdio)과 Docker 기반(포트와 streamable-http 엔드포인트)입니다. 둘 다 MCP_TRANSPORT(기본값 stdio)로 지원됩니다. Docker 이미지는 기본값을 streamable-http로 설정합니다. config.py / server.py를 참조하세요.

환경 변수

MONARCH_PASSWORD와 MONARCH_TOTP_SECRET은 다른 비밀값과 동일하게 취급하세요. obot의 단일 사용자 MCP 서버 모델은 관리자가 서버를 구성할 때 이러한 필드를 "sensitive"로 표시합니다. 그 기능을 사용하세요.

실행하기

obot, 명령어/uvx 기반(stdio)

uvx --from git+https://<your-fork-url> monarch-mcp

(이 포크를 어딘가에 푸시한 후에 — 이 코드가 현재 어디에 있는지에 대한 내용은 이 README 끝의 참고 사항을 참조하세요.)

obot, Docker 기반(streamable-http)

docker build -t monarch-mcp2-obot:local .
docker volume create monarch-session

docker run -d --rm \
  -p 8000:8000 \
  -v monarch-session:/data \
  -e MONARCH_EMAIL=you@example.com \
  -e MONARCH_PASSWORD=... \
  -e MONARCH_TOTP_SECRET=...  `# omit if your account doesn't use authenticator-app MFA` \
  monarch-mcp2-obot:local

obot의 Docker 기반 MCP 서버 구성을 이 컨테이너의 포트 8000에 있는 streamable-http 엔드포인트로 지정하세요. 세션 상태는 monarch-session 볼륨에 저장되므로, 컨테이너를 다시 시작하거나 재배포해도 다시 로그인할 필요 없이 유지됩니다.

로컬 개발(stdio, Docker 없음)

uv sync
uv run monarch-mcp

테스트

uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src/monarch_mcp/auth_runtime.py src/monarch_mcp/config.py \
  src/monarch_mcp/server.py src/monarch_mcp/groups/auth.py src/monarch_mcp/tool_metadata.py

(mypy --strict는 이 포크가 작성했거나 상당히 변경한 파일에만 적용됩니다. 상속된 그룹 모듈은 이 포크에서 엄격한 타입 검사를 다시 수행하지 않았습니다 — ROADMAP.md 참조.)

이 코드의 위치

이 코드는 로컬에서 빌드하고 검증했습니다(실제 MCP initialize 핸드셰이크를 상대로 설치, 테스트, 실행 — 두 전송 방식 모두). 그러나 이 작업의 일부로 호스팅된 git 원격 저장소에 푸시되지는 않았습니다. uvx --from git+...로 가리키기 전에 자신의 포크/원격 저장소로 푸시하고, 로컬 체크아웃 대신 해당 원격 저장소에서 빌드한다면 위의 Docker 빌드 지침도 그에 맞게 업데이트하세요.

라이선스

MIT, 업스트림에서 상속됨. LICENSE 참조.