Money Lover MCP 서버

비공식 Money Lover REST API를 래핑하는 Model Context Protocol (MCP) 서버의 Node.js 구현입니다. 이 서버는 인증, 지갑, 카테고리, 거래, 이벤트, 부채 및 정적 구성을 포함하는 27개의 MCP 도구를 제공하여 AI 어시스턴트나 MCP 호환 클라이언트가 개인 금융 데이터를 조회하고 관리할 수 있도록 합니다.

기능

• EMAIL/PASSWORD 환경 변수를 통한 자동 인증 — 대부분의 도구에서 토큰을 전달할 필요가 없습니다.

• 사용자 정보, 지갑, 카테고리, 거래, 이벤트, 부채, 아이콘, 제공자 및 정적 구성을 다루는 23개의 읽기 도구.

• 4개의 쓰기 도구: 거래, 지갑, 카테고리 생성, 수정 및 삭제.

• LLM 컨텍스트를 관리하기 쉽게 유지하기 위해 대규모 응답은 자동으로 잘립니다 (limit 매개변수를 통해 구성 가능).

• Claude Code, Claude Desktop, Cursor 및 모든 MCP 호스트와 호환되는 Stdio 기반 서버.

• ~/.moneylover-mcp/ 경로에 이메일별 토큰 캐싱 및 인증 오류 시 자동 새로 고침.

Related MCP server: YNAB Assistant

사전 요구 사항

• Node.js 22 이상.

• Money Lover 계정 자격 증명.

설치

npm install

사용법

Stdio를 통해 MCP 서버를 실행합니다:

npm start

프로젝트 범위 구성 (Claude Code)

프로젝트 루트에 .mcp.json을 추가합니다:

{
  "mcpServers": {
    "mcp-moneylover": {
      "command": "node",
      "args": ["/absolute/path/to/moneylover-mcp/src/server.js"],
      "env": {
        "EMAIL": "your@email.com",
        "PASSWORD": "your-password"
      }
    }
  }
}

그리고 .claude/settings.json에서 활성화합니다:

{ "enabledMcpjsonServers": ["mcp-moneylover"] }

전역 구성 (Claude Desktop / Cursor)

{
  "mcpServers": {
    "mcp-moneylover": {
      "command": "npx",
      "args": ["@ferdhika31/moneylover-mcp@latest"],
      "env": {
        "EMAIL": "your@email.com",
        "PASSWORD": "your-password"
      }
    }
  }
}

사용 가능한 도구

인증

사용자

지갑

카테고리

거래

정적 및 구성

도구 사용 예시

모든 도구에 대한 프롬프트 예시, 필수 vs 선택 필드, 주의 사항 및 일반적인 다단계 패턴: docs/examples.md.

라이브러리 사용

import { MoneyloverClient } from './src/moneyloverClient.js';

const token = await MoneyloverClient.getToken(email, password);
const client = new MoneyloverClient(token);

const wallets = await client.getWallets();
const txns = await client.getTransactions(walletId, '2026-01-01', '2026-04-30');
await client.addTransaction({ walletId, categoryId, amount: '50000', date: '2026-04-18' });
await client.editTransaction('txn-id', { amount: '60000', note: 'updated' });
await client.deleteTransaction('txn-id');

테스트

단위 테스트

모의 단위 테스트 — 실시간 API 호출 불필요:

npm test

통합 테스트 (mcp-tester)

mcp-tester는 ReAct 에이전트 기반의 MCP 테스트 프레임워크입니다. 서버를 시작하고, 자연어 프롬프트에 응답하여 도구를 호출하도록 LLM을 구동하며, 올바른 인수로 올바른 도구가 호출되었는지 확인합니다.

설치

pipx install --index-url https://pypi.artifacts.furycloud.io/simple/ mcp-tester

구성

tests/mcp-tester/mcps.json — 자격 증명을 사용하여 로컬 서버를 가리킵니다:

{
  "mcp-moneylover": {
    "command": "node",
    "args": ["/absolute/path/to/src/server.js"],
    "transport": "stdio",
    "env": {
      "EMAIL": "your@email.com",
      "PASSWORD": "your-password"
    }
  }
}

실행

mcp-tester run-tests \
  --mcps tests/mcp-tester/mcps.json \
  --model gpt-4o-mini \
  --concurrent-runs 3 \
  tests/mcp-tester/read-tools.yaml

결과

tests/mcp-tester/read-tools.yaml에는 모든 읽기 도구를 다루는 25개의 통합 테스트가 포함되어 있습니다:

total 25, success 25, failures 0

테스트를 안정적으로 만드는 핵심 결정 사항:

• 읽기 도구에 토큰 매개변수 없음 — 선택적 token 필드를 노출하면 LLM이 지갑 ID를 해당 필드에 주입하는 문제가 발생했습니다. 서버는 환경 변수를 통해 자동으로 인증합니다.

• 응답 잘림 — 여러 엔드포인트가 공유 MoneyLover 데이터베이스에서 수십만 개의 레코드를 반환합니다. 도구는 LLM 컨텍스트를 제어하기 위해 limit 매개변수(기본값: 20–100)를 허용합니다.

• Dict 래핑 — 모든 도구 응답은 JSON 객체를 반환하여(배열만 반환하지 않음) MCP 프레임워크 유효성 검사를 통과합니다.

쓰기 도구 테스트 (mcp-tester)

세 개의 추가 YAML 파일이 3단계 순차적 단계에 걸쳐 지갑, 카테고리 및 거래에 대한 전체 CRUD 수명 주기를 테스트합니다. 각 단계는 세 가지 리소스 유형을 모두 동시에 실행합니다.

단계를 순서대로 실행하세요. 각 단계는 이전 단계에 의존합니다:

# Phase 1: Create
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-create.yaml

# Phase 2: Edit (after Phase 1 passes)
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-edit.yaml

# Phase 3: Delete (after Phase 2 passes)
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-delete.yaml

세 단계 모두에 대한 결과:

Phase 1 (Create): total 3, success 3, failures 0
Phase 2 (Edit):   total 3, success 3, failures 0
Phase 3 (Delete): total 3, success 3, failures 0

쓰기 도구 테스트를 위한 핵심 설계 결정:

• 변이 전 탐색 — 편집 및 삭제 테스트는 에이전트에게 먼저 읽기 도구(get_wallets, get_categories, get_transactions)를 호출하여 이름으로 대상을 찾은 다음 변이 도구를 호출하도록 지시합니다. 이는 ID를 미리 알 수 없는 실제 에이전트 동작을 반영합니다.

• 쓰기 도구 어설션을 위한 args: !any — 프레임워크는 정확한 인수 일치를 요구합니다. 쓰기 도구는 에이전트가 재량에 따라 포함할 수 있는 선택적 필드(icon, with 등)를 허용합니다. !any는 도구가 호출되었고 무해한 추가 항목으로 인해 실패하지 않고 성공했음을 확인합니다. 읽기 도구 어설션은 스키마에 LLM이 자발적으로 추가할 수 있는 선택적 필드가 없기 때문에 정확한 인수 일치를 사용할 수 있습니다.

• 예측 가능한 식별자 — 테스트 리소스는 고정된 이름(MCP-Test-Wallet, MCP-Test-Category)과 고정된 메모(MCP test transaction)를 사용하여 에이전트가 테스트 실행 간에 상태를 공유할 필요 없이 편집 및 삭제 단계에서 이름을 찾을 수 있도록 합니다.

• 전체 페이로드 편집 어설션 — edit_transaction은 전체 교체 작업입니다. 테스트 프롬프트는 에이전트에게 먼저 기존 거래를 가져오고(get_transactions) 현재 필드 값을 모두 유지하며 메모만 변경하도록 지시합니다. 이는 도구 설명에 필요한 다단계 추론을 검증합니다.

보안 참고 사항

• 실제 자격 증명이나 토큰을 커밋하지 마십시오.

• 캐시된 토큰은 현재 사용자로 제한된 ~/.moneylover-mcp/에 저장됩니다.

• 모든 캐시된 세션을 취소하려면 해당 디렉토리를 삭제하십시오.