runBqlQuery
잔액, 거래 및 계정에 대해 BQL(Beancount Query Language) 쿼리를 실행합니다.
Model Context Protocol
대화 속으로 들어온 나의 장부.
Beancount를 평소 쓰는 AI 도구에 연결하세요. 재무에 관해 질문하고, 장부 파일을 다루고, 변경 이력은 Git에서 확인할 수 있습니다.
그냥 물어보세요
질문 하나로 시작하세요. 답변의 근거를 장부에서 확인할 수 있습니다.
답변의 근거
runBqlQuerySELECT sum(position) WHERE account ~ 'Assets|Liabilities'Beancount
MCP 호환 클라이언트에서 사용 가능
- Claude Code
- Claude Desktop
- Cursor
- Windsurf
- Zed
이미 사용 중인 클라이언트 연결
클라이언트를 선택하고 서버를 한 번 추가한 다음, 접근을 허용할 원장을 승인하세요.
Claude Code
터미널에서 이 명령 하나를 실행하세요.
Claude Code를 열고 /mcp를 실행하여 인증하세요. Web Beancount에 로그인하고 원장 하나 또는 전체를 승인하세요.
한 번 승인하세요. 자격 증명은 여기서부터 자동으로 갱신됩니다.
터미널
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcp원장이 여러 개인가요? 한 번에 모두 승인하세요. 어시스턴트는 listLedgers를 호출하여 접근 가능한 원장을 확인하고 각 호출에서 원장 이름을 지정하므로, 서버 하나로 모든 장부를 처리할 수 있습니다.
Web Beancount 계정을 사용하여 서버가 접근할 수 있는 원장을 승인하세요.
Web Beancount 계정이 없으신가요? beancount.io에서 가입하세요 — 원장은 git push 하나면 됩니다.
AI가 할 수 있는 일
서버는 원장, API 키, 은행 연결을 위한 집중된 도구를 제공합니다 — 원장 동사는 아래에 표시됩니다. AI가 이를 구성합니다: 파일 구조를 발견하고, 맥락을 위해 읽고, 답을 위해 질의하고, 편집을 제안합니다.
원장, API 키, 은행 도구입니다. 사용자 클라이언트가 사용 방법을 결정합니다.
listLedgerFiles
원장 저장소의 디렉터리 구조를 탐색합니다.
readLedgerFiles
.beancount 파일 및 기타 원장 문서의 내용을 읽습니다.
editLedgerFiles
원자적 git 커밋으로 파일을 생성, 업데이트, 교체 또는 삭제합니다.
보호되는 원장
장부에 쓰기 권한이 있는 AI는 약속이 아닌 설계로 신뢰를 얻습니다.
범위 지정 OAuth 2.1
연결이 접근할 수 있는 범위를 직접 선택합니다. 개인 원장 하나만 승인하면 해당 연결은 비즈니스 장부에 접근할 수 없습니다. 영향 범위를 직접 설정하는 것입니다.
드라이런 미리보기
editLedgerFiles는 dry_run 모드를 지원하여 아무것도 쓰지 않고 정확한 변경 사항을 검증하고 미리 보여주므로, 클라이언트가 먼저 diff를 표시할 수 있습니다.
모든 편집은 git 커밋입니다
변경 사항은 원장 저장소에 실제 커밋("AI edit: …")으로 반영됩니다. 표준 git 도구로 검토하고 되돌릴 수 있는 전체 감사 추적이 남습니다.
상태 비저장 서버
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가 실제로 내 원장으로 무엇을 할 수 있나요?
서버는 집중된 도구 제품군을 제공합니다 — beancount.io/.well-known/ 아래의 기계가 읽을 수 있는 발견 매니페스트에 현재 세트가 나열됩니다. 원장 도구는 Beancount Query Language 쿼리(runBqlQuery)를 실행하고, 저장소를 탐색하며(listLedgerFiles), 원장 문서를 읽고(readLedgerFiles), 원자적 git 커밋으로 파일을 생성, 업데이트, 삭제합니다(editLedgerFiles, dry_run 미리보기 모드 포함). 추가 도구는 API 키(목록, 발급, 폐기 — 발급에는 유료 플랜과 OAuth 권한 부여가 필요하며 API 키가 아님)와 은행 연결 및 가져오기(트랜잭션 스테이징, 제출, 폐기; 새로운 은행은 MCP가 아닌 브라우저에서 연결됨)를 관리합니다. AI는 이를 결합하여 질문에 답하고 편집을 제안합니다.
AI가 내가 모르는 사이에 원장을 수정할 수 있나요?
편집은 editLedgerFiles 도구를 통해 이루어집니다. dry_run 모드는 아무것도 커밋하지 않고 계획된 파일 작업을 미리 봅니다. 실제 커밋 전에 클라이언트가 묻는지 여부는 클라이언트에 따라 다릅니다. 커밋된 모든 변경은 실제 git 커밋으로 기록되며, 표준 git 도구로 되돌릴 수 있는 전체 감사 추적을 제공합니다. 커밋 경로는 쓰기 후 검증 오류를 보고할 수 있으므로, 먼저 미리 보고 나중에 원장을 검증하세요.
내 데이터가 제3자에게 전송되나요?
장부 데이터는 Web Beancount 백엔드를 통과하여 AI 클라이언트에 도구 결과로 반환됩니다. 선택한 AI 모델이 해당 결과를 받으므로, 해당 제공업체의 데이터 정책도 적용됩니다. 각 인증된 세션은 하나의 장부로 범위가 제한됩니다.
장부를 다음 대화에 가져오세요.
Beancount MCP 서버는 현재 모든 Web Beancount 사용자에게 제공됩니다. 원장은 git push 한 번이면 됩니다.