mf-accounting-voucher-mcp

머니포워드 클라우드 회계의 공식 MCP 서버가 미지원하는 기능을 보완하는 로컬 MCP 서버입니다. REST API v3를 직접 호출하며, 공식 MCP(리모트)와 병용합니다.

제공 도구

참고: 연계 내역의 '대상 외' 처리(対象外)는 REST API에 존재하지 않으므로 제공하지 않습니다. 증빙 파일 다운로드도 마찬가지로 API 미지원입니다. 공식 MCP가 이미 제공하는 기능(getJournals 등)은 재구현하지 않습니다.

증빙 파일의 바이너리는 LLM을 경유하지 않습니다. 이 서버(Node 프로세스)가 로컬 파일 경로를 받아 읽고 base64로 변환하여 API로 전송합니다.

Related MCP server: freee-chat-mcp-server

셋업

1. 앱 포털에서 앱 등록

머니포워드 앱 포털에서 앱을 생성하고 다음을 설정합니다.

• 리다이렉트 URI: http://127.0.0.1:53682/callback

• 스코프:

  • mfc/accounting/voucher.write(증빙 등록, 삭제)

  • mfc/accounting/journal.write(분개 등록, 갱신, 삭제)

발급된 클라이언트 ID / 클라이언트 시크릿을 기록해 둡니다.

2. 설치 및 빌드

pnpm install && pnpm run build

3. 환경 변수 설정

export MF_CLIENT_ID="（クライアントID）"
export MF_CLIENT_SECRET="（クライアントシークレット）"

4. 최초 인가

pnpm run auth

브라우저가 열리므로 머니포워드에 로그인하여 인가합니다. 토큰은 ~/.mf-accounting-voucher-mcp/tokens.json(mode 600)에 저장되며, 이후에는 자동으로 리프레시됩니다.

Claude Desktop / Cowork 등록

한 번 등록하면 클라이언트 기동 시 MCP 서버는 자동으로 실행됩니다. 일상적으로 수동 기동할 필요가 없습니다.

권장: 키체인 이용(시크릿을 설정 파일에 쓰지 않음)

최초 1회만 인증 정보를 macOS 키체인에 등록합니다:

security add-generic-password -s mf-accounting-voucher-mcp -a client_id -w '（クライアントID）' -U
security add-generic-password -s mf-accounting-voucher-mcp -a client_secret -w '（クライアントシークレット）' -U

claude_desktop_config.json의 mcpServers에는 기동 스크립트를 등록합니다(경로는 실제 설치 위치로 바꿔 주세요):

{
  "mcpServers": {
    "mf-accounting-voucher-mcp": {
      "command": "/path/to/mf-accounting-voucher-mcp/scripts/mf-accounting-voucher-mcp.sh",
      "args": []
    }
  }
}

최초 OAuth 인가도 스크립트 경유로 실행할 수 있습니다(환경 변수 설정 불필요):

scripts/mf-accounting-voucher-mcp.sh auth

대안: 환경 변수를 설정 파일에 직접 작성

{
  "mcpServers": {
    "mf-accounting-voucher-mcp": {
      "command": "node",
      "args": ["/path/to/mf-accounting-voucher-mcp/dist/index.js"],
      "env": {
        "MF_CLIENT_ID": "（クライアントID）",
        "MF_CLIENT_SECRET": "（クライアントシークレット）"
      }
    }
  }
}

이 방법은 시크릿이 설정 파일에 평문으로 남는다는 점에 주의하세요.

사용 예

「この領収書（/Users/xxx/Downloads/receipt.pdf）を仕訳 XXXX に添付して」
→ post_vouchers が呼ばれ、添付結果（voucher_file_ids）が返る

「仕訳 XXXX の証憑 a60cd25d-... の添付を解除して」
→ delete_voucher

「仕訳 XXXX を削除して」
→ delete_journal（実行前に仕訳内容の提示と明示的な確認が入る）

첨부 결과는 공식 MCP의 getJournalById로 대상 분개를 조회하여 voucher_file_ids에 반영되었는지로 검증할 수 있습니다.

주의

• MF의 파일 종류·크기·매수에 대한 정확한 제한은 공식 스펙 /specs/vouchers를 참조하세요(본 서버의 상한은 로컬 측 안전장치입니다)

• 사업자(오피스) 전환은 pnpm run auth 재실행으로 수행합니다

• delete_journal은 취소할 수 없습니다. 호출 측(LLM)은 사용자의 명시적 확인을 받은 후 실행하도록 설계되어 있습니다