Beancount MCP: 원장을 AI 어시스턴트에 연결하기

AI 어시스턴트에게 지난달 지출이 얼마인지, 어떤 계정을 조정해야 하는지, 또는 거래가 어디에 속하는지 물어보세요. Beancount MCP는 호스팅된 원장의 쿼리, 계정, 소스 파일에 접근 권한을 제공하므로, 어시스턴트는 장부를 기반으로 작업하고 답변 뒤에 있는 증거를 보여줄 수 있습니다.

쓰기 권한이 있으면 어시스턴트가 거래를 추가하고 원장 파일을 업데이트할 수도 있습니다. 지원되는 편집을 미리 보거나, 제안된 항목을 검토하고, 변경 후 원장을 확인하도록 요청할 수 있습니다.

MCP는 Model Context Protocol의 약자로, AI 애플리케이션을 외부 도구 및 데이터에 연결하기 위한 표준입니다. 이 연결은 Beancount.io에 호스팅된 원장과 함께 작동합니다. 어시스턴트의 답변은 그곳에 기록된 거래와 가격을 반영합니다. MCP를 연결한다고 해서 해당 기록이 자동으로 최신 상태가 되는 것은 아닙니다.

AI 클라이언트 연결​

Streamable HTTP를 통한 원격 MCP를 지원하는 클라이언트를 사용하세요. 서버 URL은 다음과 같습니다:

https://beancount.io/api-gateway/mcp

Claude Code​

터미널에서 서버를 추가하세요:

claude mcp add --transport http beancount https://beancount.io/api-gateway/mcp

Claude Code를 열고 /mcp를 실행한 후 beancount를 선택하고 인증 흐름을 따르세요. Beancount.io에 로그인하고 요청된 권한을 검토하세요. /mcp로 돌아와 연결을 확인하세요. 클라이언트별 세부 사항은 Claude Code의 MCP 지침을 참조하세요.

동의 페이지에서 하나의 원장으로 접근을 제한하거나 액세스 가능한 모든 원장을 명시적으로 선택할 수 있습니다. 단일 원장 제한은 유용한 시작점입니다. 더 넓은 접근 권한이 있는 경우 alice/personal과 같이 사용할 원장을 어시스턴트에게 알려주세요. 원장 도구는 각 호출에서 대상을 식별해야 합니다.

Claude Desktop 및 웹의 Claude​

Customize → Connectors를 열고 Add custom connector를 선택한 후 서버 URL을 입력하고 Beancount.io 계정을 연결하세요. 사용하려는 대화에서 커넥터를 활성화하세요. 조직 계정의 경우 소유자가 먼저 커넥터를 추가해야 할 수 있습니다. Claude의 원격 커넥터 가이드를 따르세요.

Cursor​

개인 ~/.cursor/mcp.json에 서버를 추가하세요:

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp"
    }
  }
}

Cursor가 요청할 때 OAuth 로그인을 완료한 다음 서버의 도구를 사용할 수 있는지 확인하세요. Cursor의 MCP 문서에서 구성 및 도구 승인 설정을 다룹니다.

개인 API 키​

Bearer 자격 증명을 허용하는 클라이언트의 경우 설정 → 개인 액세스 토큰에서 개인 API 키를 만들 수 있습니다. 키를 만들려면 유료 Beancount.io 요금제가 필요합니다. 쿼리에는 ledger.read를 선택하고, 선택적으로 키를 하나의 원장으로 제한한 후 표시될 때 복사하세요. 개인 자격 증명 설정을 사용하여 클라이언트의 인증 헤더를 Authorization: Bearer YOUR_KEY로 구성하세요.

키를 공유 프로젝트 구성에 두지 마세요. OAuth 클라이언트는 로그인 흐름을 통해 자격 증명을 관리하므로 해당 경로에는 개인 키를 만들 필요가 없습니다.

지출 질문으로 시작하기​

연결 후 원장 이름을 자신의 것으로 바꿔서 다음을 시도해 보세요:

alice/personal을 사용하세요. 계정과 통화를 식별한 다음 2026년 8월 지출을 계정별로 요약하세요. 각 합계 뒤에 있는 날짜 범위와 BQL을 표시하고 통화를 분리하며 원장 검증 오류를 보고하세요. 아무것도 변경하지 마세요.

어시스턴트는 listLedgers로 원장을 발견하고, getLedgerContext로 계정 이름을 배우며, runBqlQueryStructured로 유형화된 쿼리 결과를 실행할 수 있습니다. checkLedger는 검증 오류, 항목 수, 최신 커밋을 반환합니다.

유용한 답변에는 원장, 기간, 통화, 합계, 지원 쿼리가 포함됩니다. 순자산 질문의 경우 평가 방법과 사용된 가격의 날짜도 요청하세요. 누락된 거래나 오래된 가격은 원장이 검증을 통과하더라도 답변을 바꿀 수 있습니다.

미리 보기와 함께 거래 추가​

새 항목의 경우 appendLedgerText는 일반 Beancount 텍스트를 허용하고 원장 구성에 따라 지시문을 파일로 라우팅합니다. dry_run 옵션은 커밋 전에 diff와 예상 검증 오류를 반환합니다.

예:

2026년 9월 15일자 4.50 USD 커피 구매를 준비하고 Assets:Cash에서 지불하며 Expenses:Food로 분류하세요. 해당 계정이 존재하는지 확인하고 먼저 일치하는 거래를 찾으세요. dry_run: true와 함께 appendLedgerText를 사용하고 제안된 항목과 파일 diff를 표시한 후 제 확인을 기다리세요.

해당 계정이 이미 개설되어 있다면 제안된 항목은 다음과 같습니다:

2026-09-15 * "Cafe" "Coffee"
  Expenses:Food   4.50 USD
  Assets:Cash    -4.50 USD

자신의 원장에서 계정 이름을 사용한 다음 검토를 완료하세요:

1. 미리 보기에서 날짜, 금액, 계정, 대상 파일을 확인하세요.
2. 어시스턴트가 적용할 정확한 변경 사항을 확인하세요.
3. checkLedger를 실행하고 결과 커밋과 오류를 보고하도록 요청하세요.

appendLedgerText는 기본적으로 새 검증 오류를 거부합니다. 일반 파일 변경은 editLedgerFiles를 사용하며, 한 번의 Git 커밋으로 파일을 생성, 교체, 업데이트 또는 삭제할 수 있습니다. 미리 보기에서도 diff와 예상 오류를 보고합니다. 결과를 확인하고 작성 후 checkLedger를 실행하세요. 성공적인 커밋에도 회계 오류가 포함될 수 있습니다.

반복적인 장부 관리를 위한 워크플로우 사용​

서버는 재사용 가능한 MCP 프롬프트도 제공합니다. 프롬프트를 지원하는 클라이언트는 명령 또는 프롬프트 선택기에서 이를 노출합니다:

이러한 프롬프트는 어시스턴트를 절차로 안내합니다. 선택한다고 해서 회계 작업이 실행되는 것은 아니며 추가 권한을 부여하지도 않습니다.

조정에는 명세서와 기말 잔액이 필요합니다. 깨끗한 검증 결과만으로는 모든 거래가 기록되었음을 확립할 수 없습니다. 어시스턴트에게 확인할 수 없는 항목을 식별하고 해당 질문을 보고서에 표시해 두도록 요청하세요.

은행 가져오기의 경우 먼저 Beancount.io에서 은행을 연결하세요. 연결 세부 정보를 읽으려면 관리자 액세스가 필요하며, 준비된 거래를 제출하려면 쓰기 권한과 해당 은행 연결에 대한 적절한 액세스가 필요합니다. 제출을 승인하기 전에 제안된 카테고리와 중복을 검토하세요.

액세스 및 데이터 처리 이해​

연결의 권한은 어시스턴트가 할 수 있는 작업을 결정합니다:

각 원장에 대한 기존 액세스 권한은 계속 적용됩니다. 자격 증명을 하나의 원장으로 제한하면 원장 호출이 다른 원장을 대상으로 할 수 없습니다. 제한되지 않은 자격 증명은 액세스할 수 있는 원장 중에서 선택할 수 있습니다. OAuth 클라이언트는 요청할 권한을 선택하므로 승인 전에 동의 화면을 읽으세요.

MCP 서버는 인간 승인 대화 상자를 표시하지 않습니다. 클라이언트 설정이 도구 호출 전에 언제 질문할지 결정하며, 미리 보기는 명시적으로 요청해야 합니다. 제공된 쓰기 워크플로우는 어시스턴트에게 확인을 기다리도록 지시합니다. ledger.read로 제한된 자격 증명은 쓰기 없이 분석을 원할 때 강제 경계를 제공합니다.

쿼리된 거래 및 어시스턴트가 읽은 파일을 포함한 도구 결과는 AI 클라이언트의 컨텍스트에 들어가며 해당 모델 제공자가 처리할 수 있습니다. Beancount.io는 원장, Git 기록 및 운영 기록을 보유합니다. 무상태 MCP 연결은 데이터가 보관되지 않는다는 약속이 아닙니다. 클라이언트 및 제공자의 데이터 정책도 적용됩니다.

해지된 개인 API 키는 이후 요청에서 거부됩니다. OAuth 액세스 토큰은 일반적으로 1시간 동안 유효하며, 새로 고침 토큰을 해지해도 이미 발급된 액세스 토큰이 즉시 무효화되지는 않습니다. 보호된 작업이 실행될 때 원장 액세스가 다시 확인됩니다.

자주 묻는 질문​

이것이 노트북에서 원장을 여나요?

호스팅 엔드포인트는 Beancount.io 원장에서 작동합니다. 로컬 .bean 파일을 열지 않으며 Fava 브라우저 탭을 열 필요도 없습니다.

대시보드의 AI 어시스턴트와 어떻게 다른가요?

대시보드는 자체 채팅 인터페이스를 제공합니다. MCP는 외부 AI 클라이언트에서 원장 기능을 사용할 수 있게 하며, 해당 클라이언트의 대화, 모델 및 승인 설정을 사용합니다.

도구가 보이는데 사용할 수 없는 이유는 무엇인가요?

도구 카탈로그에는 자격 증명이 허용하지 않는 작업이 포함될 수 있습니다. 오류와 부여된 권한을 확인하세요. 제한되지 않은 자격 증명도 원장 도구에 명시적인 원장 대상을 지정해야 합니다.

원장을 연결하고 장부로 확인할 수 있는 질문 하나로 시작하세요. 쿼리를 답변과 함께 유지한 다음, 원장 자체 유지 관리에 도움이 필요할 때 쓰기 권한을 추가하세요.