moneybird-mcp

Moneybird 회계 API용 Model Context Protocol 서버입니다.

Moneybird를 일련의 MCP 도구로 노출하므로 Claude와 같은 어시스턴트가 연락처를 조회하고, 인보이스를 읽고, 은행 거래를 확인하고, 시간을 기록하고, 관리(administration)에서 보고서를 가져올 수 있습니다. 쓰기 기능을 켜기 전까지는 읽기 전용이며, 도구는 개별적으로 활성화할 수 있는 툴셋으로 그룹화되고, 클라이언트는 Moneybird의 속도 제한 안에 머무르도록 자체 요청 속도를 조절합니다. 로컬 클라이언트에는 stdio, 원격 클라이언트에는 Streamable HTTP를 지원합니다.

빠른 시작

서버를 클라이언트에 등록하세요. Claude Code의 경우:

claude mcp add moneybird -- npx -y moneybird-mcp serve

그런 다음 어시스턴트에게 연결을 요청하세요. 서버는 자격 증명 없이 시작되며 connect_moneybird 도구를 노출합니다. 이 도구는 브라우저에서 Moneybird의 토큰 페이지를 열고, 거기서 생성한 토큰을 요청하며, 이를 검증하고, 관리(administration)를 선택해 저장합니다 — 대화를 벗어나지 않고요.

이를 위해서는 MCP elicitation을 지원하는 클라이언트가 필요합니다. 지원되지 않는 환경에서는 터미널에서 동일한 설정을 실행합니다:

npx moneybird-mcp login

이 과정은 동일한 단계를 안내하며 결과를 ~/.config/moneybird-mcp/credentials.json에 저장합니다.

의존하기 전에 모든 것이 정상적으로 해석되는지 확인하세요:

npx moneybird-mcp status

status는 활성화된 툴셋, 쓰기 및 삭제 설정, 자격 증명의 출처, 토큰이 접근할 수 있는 관리(administration) 항목을 출력합니다. Moneybird에 연결할 수 없으면 0이 아닌 종료 코드를 반환합니다.

Related MCP server: kalender.digital MCP Server

인증

Moneybird는 토큰을 얻는 두 가지 방법을 제공하며, 이 서버는 둘 다 지원합니다. 어느 쪽도 완전히 자동화되지는 않습니다. Moneybird는 Dynamic Client Registration도 PKCE도 구현하지 않으므로 토큰 생성이나 애플리케이션 등록을 건너뛰는 흐름은 존재하지 않습니다. 이는 이 서버의 제한이 아니라 Moneybird API의 제한입니다. connect_moneybird 도구가 하는 일은 그 하나를 둘러싼 모든 단계를 제거하는 것입니다 — 올바른 페이지를 열고 결과를 대신 캡처합니다.

개인 API 토큰. https://moneybird.com/user/applications/new에서 직접 생성하고, 원하는 스코프를 선택한 다음, moneybird-mcp login에 붙여넣으세요. 가장 간단한 방법입니다. 스코프는 생성 시점에 고정되며, Moneybird는 현재 이 토큰을 만료시키지 않습니다 — 즉 자동으로 교체할 수도 없다는 뜻입니다. 비밀번호처럼 취급하세요.

OAuth 애플리케이션. 같은 곳에서 애플리케이션을 등록한 다음:

export MONEYBIRD_CLIENT_ID=...
export MONEYBIRD_CLIENT_SECRET=...
npx moneybird-mcp login --oauth

서버는 Moneybird의 인증 페이지를 열고, http://127.0.0.1:51739/callback에서 리디렉션을 받아 코드를 교환합니다. Moneybird는 리디렉션 URI를 정확히 일치시키므로 해당 URI는 애플리케이션에 그대로 등록되어 있어야 합니다. 다른 포트를 사용하려면 --port를, 리디렉션 대신 브라우저에 코드를 표시하려면 --oob를 사용하세요 — 루프백 리스너를 열 수 없는 환경에서 유용합니다. OAuth 토큰은 Moneybird에서 취소할 수 있으며, 만료 시간이 있으면 자동으로 갱신됩니다.

프롬프트 없이 토큰을 저장하려면, 예를 들어 프로비저닝 스크립트에서:

npx moneybird-mcp login --token "$MONEYBIRD_TOKEN"

moneybird-mcp logout은 저장된 파일을 제거합니다. OAuth 자격 증명의 경우 인증 자체를 취소하지는 않습니다 — 그 작업은 Moneybird에서 하세요.

스코프, 갱신 동작 및 정확한 흐름은 docs/authentication.md를 참조하세요.

구성

구성은 환경 변수에서 가져옵니다. CLI 플래그가 이를 덮어씁니다.

환경 변수

명령

플래그

툴셋

도구는 Moneybird의 자체 도메인별로 그룹화됩니다. 다섯 개는 기본적으로 활성화되고, 나머지 네 개는 선택 사항입니다.

명시적으로 설정하거나, 기본값에 추가하거나, 기본값에서 제외하세요:

moneybird-mcp serve --toolsets core,invoicing     # exactly these two
moneybird-mcp serve --toolsets all                # everything
moneybird-mcp serve --toolsets reports            # exactly reports
moneybird-mcp serve --toolsets -banking,-time     # the defaults minus two

목록의 어느 위치에 있든 -name 항목이 있으면 목록이 빈 상태가 아닌 기본값에서 시작함을 의미합니다. all은 다른 모든 것보다 우선합니다. 알 수 없는 이름은 조용히 무시되는 것이 아니라 오류입니다.

도구별 전체 목록은 docs/tools.md에 있거나, moneybird-mcp tools를 실행하면 됩니다.

안전 모델

모든 도구는 세 가지 액세스 등급 중 하나를 선언하며, 서버는 현재 설정이 허용하는 도구만 등록합니다. 등록되지 않은 도구는 모델에게 보이지 않습니다 — 실수로 호출되거나 대화를 통해 만들어질 수 없습니다.

• read — 항상 등록됩니다.

• write — 데이터를 생성하거나 수정합니다. --allow-write 또는 MONEYBIRD_ALLOW_WRITE=true가 필요합니다.

• destroy — --allow-delete 및 --allow-write가 필요합니다. --allow-delete만으로는 아무 효과가 없습니다.

삭제는 쓰기와 별도로 제한되는데, 두 실패 모드는 비교할 수 없기 때문입니다. 잘못된 쓰기는 수정할 수 있는 기록을 남기지만, 삭제나 고객에게 보낸 인보이스는 API가 되돌릴 수 있는 것이 아닙니다. 어시스턴트가 인보이스를 작성할 수 있도록 쓰기를 활성화한다고 해서 부기 기록을 삭제할 수 있게 해서는 안 됩니다. 따라서 destroy 등급은 삭제와 연락처에게 문서를 보내는 것처럼 실질적으로 되돌릴 수 없는 호출을 모두 포함합니다.

읽기 전용이 기본값입니다. 필요한 최소한만 활성화하십시오:

claude mcp add moneybird --env MONEYBIRD_ALLOW_WRITE=true -- npx -y moneybird-mcp serve

클라이언트 설정

Claude Code

claude mcp add moneybird -- npx -y moneybird-mcp serve

쓰기 액세스와 더 폭넓은 도구 선택이 필요할 때:

claude mcp add moneybird \
  --env MONEYBIRD_ALLOW_WRITE=true \
  --env MONEYBIRD_TOOLSETS=all \
  -- npx -y moneybird-mcp serve

Claude Desktop

claude_desktop_config.json에 서버를 추가하십시오:

{
  "mcpServers": {
    "moneybird": {
      "command": "npx",
      "args": ["-y", "moneybird-mcp", "serve"],
      "env": {
        "MONEYBIRD_ALLOW_WRITE": "true"
      }
    }
  }
}

이 파일은 macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows에서는 %APPDATA%\Claude\claude_desktop_config.json에 있습니다. 편집한 후 앱을 다시 시작하십시오.

모든 stdio 클라이언트

이 서버는 일반 stdio MCP 서버입니다. moneybird-mcp serve를 실행하고 stdin과 stdout을 통해 JSON-RPC를 주고받으십시오. 진단 정보는 stderr로 전달되며 stdout으로는 절대 출력되지 않습니다.

{
  "command": "npx",
  "args": ["-y", "moneybird-mcp", "serve"],
  "env": {
    "MONEYBIRD_API_TOKEN": "..."
  }
}

자격 증명을 디스크에 저장하고 싶지 않다면 클라이언트의 env 블록에 MONEYBIRD_API_TOKEN을 설정하십시오. 이 값은 credentials.json의 어떤 내용보다 우선합니다.

Docker 및 자체 호스팅

docker build -t moneybird-mcp .
docker run --rm -p 3000:3000 -e MONEYBIRD_API_TOKEN=... moneybird-mcp

이미지는 기본적으로 0.0.0.0:3000에서 HTTP 전송을 사용하며 /mcp와 인증이 필요 없는 /healthz를 노출합니다. 인증 없이 공개 주소에 배포하지 마십시오.

docs/hosting.md에는 세 가지 HTTP 인증 모드, 다중 테넌트 passthrough 배포, 리버스 프록시 참고 사항, 원격 클라이언트 연결 방법이 설명되어 있습니다.

속도 제한

Moneybird는 IP당 5분에 150개 요청을 허용하며, /reports 엔드포인트는 5분에 50개를 허용합니다. 클라이언트는 두 예산 모두에 대해 자체 슬라이딩 윈도 카운터를 유지하고 한도를 초과할 요청은 지연시키므로, 일반적인 사용에서는 429가 발생하지 않습니다. Moneybird가 어쨌든 429를 반환하면 클라이언트는 Retry-After를 준수하며, 그 외에는 완전한 지터(full jitter) 방식으로 지수적 백오프를 수행하고 최대 MONEYBIRD_MAX_RETRIES회까지 재시도합니다.

예산은 토큰이 아니라 IP 기준입니다. 하나의 이그레스 주소 뒤에 있는 여러 인스턴스가 이 예산을 공유하며, 로컬 카운터는 서로를 볼 수 없습니다. 배포 규모를 이에 맞게 조정하십시오.

개발

npm install
npm run build      # before typecheck: the docs generator imports the built output
npm run typecheck
npm test
npm run format

docs/tools.md는 도구 정의에서 생성됩니다. 도구를 추가하거나 변경한 후 다시 생성하십시오:

npm run docs:tools

spec/endpoints.json은 Moneybird가 공개한 작업 목록을 고정하며, 테스트는 도구가 호출하는 모든 경로가 이 목록과 일치하는지 확인합니다. Moneybird가 API 변경 사항을 제공하면 이 파일을 새로 고치십시오:

npm run spec:refresh
npm test

새로 고친 후 엔드포인트 테스트가 실패한다면, 도구가 의존하는 경로가 이동했거나 제거되었음을 의미합니다.

기여

이슈와 풀 리퀘스트는 https://github.com/HalloSouf/moneybird-mcp에서 환영합니다. 풀 리퀘스트를 열기 전에 npm run typecheck, npm test, npm run format:check를 실행해 주십시오. CI는 Node 20 및 22에서 동일한 검사를 실행합니다.

라이선스

MIT. LICENSE를 참조하십시오.