Model Context Protocol
이미 사용 중인 AI 도구에서 원장과 대화하세요
Beancount MCP 서버가 일반 텍스트 원장을 Claude Code, Claude Desktop, Cursor, Windsurf, Zed — 모든 MCP 호환 AI 클라이언트에 연결합니다. 복사-붙여넣기 없이, 내보내기 없이, 그냥 물어보세요.
MCP 서버 URL
https://beancount.io/api-gateway/mcp> 오늘 내 순자산은 얼마인가요?
⏺ runBqlQuery("SELECT sum(position) WHERE account ~ 'Assets|Liabilities'")
오늘의 순자산은 128,450.32 USD입니다.
> 어제의 42 USD 팀 저녁 식사를 추가하고 커밋하세요
⏺ editLedgerFiles(dry_run: true) → +1 transaction
⏺ git commit a1b4f2e — "AI edit: add team dinner transaction"
완료 — 전체 감사 추적과 함께 원장에 커밋했습니다.
그냥 물어보세요
"지난 분기에 여행에 얼마를 썼지?"에 답하려면 BQL 문법을 알고, 올바른 파일을 찾고, 결과를 채팅에 복사해야 했습니다. 이제는 한 문장이면 됩니다.
“오늘 내 순자산은 얼마인가요?”
실제 원장에서 가져온 실시간 답변 — 추측이 아닙니다.
“지난달 지출 요약”
AI가 BQL 쿼리를 작성하고 결과를 읽어줍니다.
“거래를 추가하고 git에 커밋하세요”
원장 저장소의 실제 커밋, 다른 커밋처럼 되돌릴 수 있습니다.
“내 원장 저장소에는 무엇이 있나요?”
에디터를 떠나지 않고 .beancount 파일을 탐색하고 읽으세요.
AI가 할 수 있는 일
서버는 네 가지 원장 도구를 제공합니다. AI가 이를 조합합니다: 파일 구조 탐색, 컨텍스트 읽기, 답변 쿼리, 편집 제안.
runBqlQuery
잔액, 거래 및 계정에 대해 BQL(Beancount Query Language) 쿼리를 실행합니다.
listLedgerFiles
원장 저장소의 디렉터리 구조를 탐색합니다.
readLedgerFiles
.beancount 파일 및 기타 원장 문서의 내용을 읽습니다.
editLedgerFiles
원자적 git 커밋으로 파일을 생성, 업데이트, 교체 또는 삭제합니다.
1분 안에 연결하세요
AI 클라이언트를 선택하세요. 복사. 붙여넣기. 질문하세요.
- 터미널에서 이 명령 하나를 실행하세요.
- Claude Code가 브라우저 창을 엽니다 — 로그인하고 연결할 원장을 선택하세요.
- 한 번 승인하세요. 자격 증명은 여기서부터 자동으로 갱신됩니다.
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcp원장이 두 개 이상인가요? 서버를 다른 이름으로 다시 추가하고 다른 원장을 자체 프롬프트에서 승인하세요:
claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcpWeb Beancount 계정이 없으신가요? beancount.io에서 가입하세요 — 원장은 git push 하나면 됩니다.
보호되는 원장
장부에 쓰기 권한이 있는 AI는 약속이 아닌 설계로 신뢰를 얻습니다.
원장 범위 OAuth 2.1
하나의 세션은 정확히 하나의 원장에 대해 승인됩니다. 개인 원장에 대한 세션은 사업 원장에 접근할 수 없습니다 — 영향 범위가 제한됩니다.
모든 편집은 git 커밋입니다
변경 사항은 원장 저장소에 실제 커밋("AI edit: …")으로 반영됩니다. 표준 git 도구로 검토하고 되돌릴 수 있는 전체 감사 추적이 남습니다.
드라이런 미리보기
editLedgerFiles는 dry_run 모드를 지원하여 아무것도 쓰지 않고 정확한 변경 사항을 검증하고 미리 보여주므로, 클라이언트가 먼저 diff를 표시할 수 있습니다.
상태 비저장 서버
MCP 서버는 AI 클라이언트 대화에 이미 포함된 내용 외에는 아무것도 저장하지 않습니다. 원장은 현재 있는 위치에 그대로 유지됩니다.
전체 원장은 이미 git 저장소입니다. Git for Beancount 작동 방식 보기
자주 묻는 질문
MCP란 무엇이며 Beancount에 왜 중요한가요?
MCP(Model Context Protocol)는 AI 어시스턴트가 외부 도구와 데이터 소스에 구조적이고 안전하게 접근할 수 있게 하는 개방형 표준입니다. 데이터를 추측하거나 붙여넣기를 요청하는 대신, AI 클라이언트가 원장에 직접 연결하여 실제 데이터를 조회하고, 실제 파일을 읽고, 정확한 편집을 수행합니다.
어떤 AI 클라이언트가 Beancount MCP 서버와 작동하나요?
OAuth 2.1을 지원하는 모든 MCP 호환 클라이언트가 즉시 작동합니다. 여기에는 Claude Code, Claude Desktop, Cursor, Windsurf, Zed가 포함됩니다. OAuth 2.1을 지원하지 않는 클라이언트는 beancount.io 계정 설정에서 생성된 정적 토큰으로 연결할 수 있습니다.
원장을 어떻게 연결하나요?
클라이언트의 MCP 구성에 서버 URL을 추가하세요. 처음 사용 시 클라이언트가 브라우저 창을 열고, Web Beancount 계정으로 로그인한 후 액세스를 허용할 원장을 선택합니다. 이후 클라이언트가 자동으로 자격 증명을 저장하고 갱신합니다.
AI가 실제로 내 원장으로 무엇을 할 수 있나요?
서버는 네 가지 도구를 제공합니다. runBqlQuery는 Beancount Query Language 쿼리를 실행하고, listLedgerFiles는 원장 저장소를 탐색하며, readLedgerFiles는 원장 문서를 읽고, editLedgerFiles는 원자적 git 커밋으로 파일을 생성, 업데이트 또는 삭제합니다. AI는 이들을 결합하여 질문에 답하고 편집을 제안합니다.
AI가 내가 모르는 사이에 원장을 수정할 수 있나요?
편집은 editLedgerFiles 도구를 통해 이루어지며, 이 도구는 잘 작동하는 MCP 클라이언트가 실행 전에 사용자에게 표시합니다. dry_run 모드는 아무것도 쓰지 않고 정확한 변경 사항을 미리 보여주며, 모든 커밋된 변경은 실제 git 커밋으로, 표준 git 도구로 되돌릴 수 있는 전체 감사 추적을 제공합니다.
내 데이터가 제3자에게 전송되나요?
원장 데이터는 이미 원장을 관리하는 Web Beancount 백엔드를 통해 흐르며, 구조화된 결과로 AI 클라이언트에 반환됩니다. 세션은 원장 범위로 지정되어, 각 세션은 사용자가 승인한 원장에만 정확히 접근할 수 있으며, MCP 서버는 AI 클라이언트 대화에 포함된 내용 외에는 아무것도 저장하지 않습니다.
어떻게 구축되었는지 궁금하신가요? 블로그에서 엔지니어링 FAQ 읽기
회계 데이터와 AI 워크플로우의 만남
Beancount MCP 서버는 현재 모든 Web Beancount 사용자에게 제공됩니다. 원장은 git push 한 번이면 됩니다.