Beancount MCP: 원장을 Claude, Cursor, 그리고 모든 AI 어시스턴트에 연결하세요

Web Beancount, MCP 서버 출시 — 이미 사용 중인 Claude, Cursor, 그리고 모든 AI 도구에서 원장과 대화하세요

여러분의 회계 데이터가 AI 워크플로를 만납니다. 복사-붙여넣기 없이. 내보내기 없이. 그냥 물어보세요.

오늘, Web Beancount는 Beancount MCP 서버를 발표합니다 — 여러분의 Beancount 원장을 Claude Desktop, Claude Code, Cursor, Windsurf, 또는 다른 모든 MCP 호환 AI 클라이언트에 직접 연결할 수 있게 해주는 Model Context Protocol (MCP) 엔드포인트입니다. 파워 유저는 처음으로 탭을 전환하거나 워크플로를 떠나지 않고 — 이미 머물고 있는 AI 도구 안에서 — 회계 질문을 하고, BQL 쿼리를 실행하며, 심지어 원장 파일을 편집할 수 있습니다.

플레인 텍스트 Beancount 파일이 강력한 이유는 바로 그것들이 그냥 파일이기 때문입니다. 하지만 "지난 분기에 여행에 얼마를 썼지?"에 답하려면 여전히 BQL 문법을 알아야 하고, 파일이 어디 있는지 알아야 하며, 결과를 채팅에 복사해야 합니다. Beancount MCP 서버는 그 마찰을 완전히 제거합니다.

AI 클라이언트에 Beancount MCP 서버를 구성하면, 다음을 할 수 있습니다:

"오늘 내 순자산은 얼마지?"라고 물으면 실제 원장에서 도출된 실시간 답변을 얻습니다
지난달 지출 요약을 요청하면 AI가 여러분을 위해 BQL 쿼리를 작성하게 합니다
AI에게 거래를 추가하라고 지시하고 그 변경이 원장의 git 저장소에 커밋되는 것을 지켜봅니다
에디터를 떠나지 않고 .beancount 파일을 탐색하고 읽습니다

이 서버는 원장 범위로 제한됩니다: 각 MCP 세션은 OAuth 2.1을 사용하여 정확히 하나의 원장에 대해 인가됩니다. Claude Code 같은 클라이언트는 인가 흐름을 자동으로 발견하고 완료합니다 — 수동 토큰 관리가 필요 없습니다. 여러분의 원장은 이미 있던 곳, 즉 Web Beancount 백엔드에 그대로 유지됩니다: AI 클라이언트가 우리 서버에 구조화된 도구 호출을 보내면, 서버는 여러분을 대신하여 원장을 읽거나 편집하고 결과를 반환합니다. MCP 서버 자체는 AI 클라이언트의 대화가 보유한 것 이상으로는 아무것도 저장하지 않습니다.

Beancount MCP 서버는 오늘부터 모든 Web Beancount 사용자에게 제공됩니다.

시작하기

Beancount MCP 서버가 실시간으로 제공됩니다. 1분도 안 걸려 AI 클라이언트에 추가하세요.

MCP 서버 URL

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

Claude Code (권장 — 전체 OAuth 2.1 흐름, 토큰 불필요)

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

처음 사용할 때, Claude Code는 브라우저 창을 엽니다. 브라우저 프롬프트가 바로 어떤 원장을 연결할지 고르는 곳입니다 — 한 번 승인하면 자격 증명이 자동으로 갱신됩니다. 원장이 여러 개인가요? 다른 이름으로 서버를 다시 추가하고(claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcp) 각각의 프롬프트에서 다른 원장을 인가하세요.

Claude Desktop / Cursor / Windsurf / Zed

클라이언트의 MCP 설정(claude_desktop_config.json 또는 이에 상응하는 것)에 서버를 추가하세요. OAuth 2.1을 지원하는 클라이언트는 처음 사용할 때 동일한 브라우저 프롬프트를 엽니다 — 거기서 원장을 고르세요:

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

클라이언트가 아직 OAuth 흐름을 지원하지 않는다면, beancount.io 계정 설정에서 (하나의 원장으로 범위가 제한된) 정적 토큰을 생성하여 헤더로 전달하세요:

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Web Beancount 계정이 없으신가요? **beancount.io**에서 가입하세요 — 여러분의 원장은 git push 한 번이면 됩니다.

자주 묻는 질문

고객 FAQ

MCP란 무엇이며 Beancount에 왜 중요한가요?

MCP (Model Context Protocol)는 AI 어시스턴트가 외부 도구와 데이터 소스를 구조화되고 안전한 방식으로 호출할 수 있게 해주는 개방형 표준입니다. AI를 위한 USB 포트라고 생각하세요: AI가 추측하거나 여러분에게 데이터를 붙여넣도록 요청하는 대신, 여러분의 시스템에 직접 연결됩니다. Beancount 사용자에게 이것은 AI 클라이언트가 실제 원장 데이터를 조회하고, 실제 파일을 읽으며, 정확한 편집을 할 수 있다는 뜻입니다 — 그 안에 무엇이 있을지 추측하는 것이 아니라요.

어떤 AI 클라이언트가 Beancount MCP 서버와 작동하나요?

OAuth 2.1을 지원하는 모든 MCP 호환 클라이언트가 기본으로 작동합니다. Beancount MCP 서버는 PKCE를 사용한 전체 OAuth 2.1 인가 흐름을 구현하므로, Claude Code 같은 클라이언트는 서버의 인가 엔드포인트를 자동으로 발견하고 여러분에게 로그인을 요청합니다 — 수동 토큰 복사나 구성이 필요 없습니다. 접근을 승인하고 나면, 클라이언트가 자격 증명을 자동으로 저장하고 갱신합니다.

알려진 MCP + OAuth 2.1 지원 클라이언트로는 Claude Code CLI, Claude Desktop, Cursor, Windsurf, Zed가 있습니다. MCP 생태계가 성장하면서, OAuth 2.1 MCP 사양을 따르는 모든 새 클라이언트가 우리 쪽 변경 없이 작동할 것입니다.

제 원장을 어떻게 연결하나요?

OAuth 2.1을 지원하는 클라이언트(예: Claude Code)의 경우:

Beancount MCP 서버 URL을 클라이언트의 MCP 구성에 추가하세요.
클라이언트가 접근을 인가하기 위해 자동으로 브라우저 창을 엽니다.
Web Beancount 계정으로 로그인하고 접근 권한을 부여할 원장을 고르세요.
완료 — 이후로는 클라이언트가 토큰 저장과 갱신을 처리합니다.

OAuth 2.1을 지원하지 않는 클라이언트의 경우, Web Beancount 계정 설정에서 (하나의 원장으로 범위가 제한된) 정적 토큰을 생성하여 Authorization: Bearer 헤더로 전달하세요.

이것은 대시보드의 "Ask AI" 채팅 기능과 같은 것인가요?

둘은 동일한 기저 원장 도구(BQL 쿼리, 파일 읽기/쓰기)를 공유하지만, MCP 서버는 다른 진입점입니다. 대시보드의 Ask AI 기능은 Cloudflare 기반 Claude Code 샌드박스를 갖춘 호스팅형 채팅 경험입니다. MCP 서버는 여러분이 선택한 자신의 AI 클라이언트에서 연결하는 프로토콜 엔드포인트로 — 더 많은 제어, 더 많은 모델, 그리고 기존 워크플로와의 더 깊은 통합을 제공합니다.

AI가 제 원장으로 실제로 무엇을 할 수 있나요?

MCP 서버는 네 가지 도구를 노출합니다:

도구	하는 일
`runBqlQuery`	BQL (Beancount Query Language)을 실행하여 잔액, 거래, 계정을 조회
`listLedgerFiles`	원장 저장소의 디렉터리 구조를 탐색
`readLedgerFiles`	`.beancount` 파일 및 기타 원장 문서의 내용을 읽기
`editLedgerFiles`	원자적 git 커밋으로 파일을 생성, 업데이트, 교체, 삭제

AI는 이것들을 결합할 수 있습니다: 파일 구조를 발견하고, 컨텍스트를 위해 관련 파일을 읽고, 질문에 답하기 위해 BQL 쿼리를 작성하거나, 편집을 제안하고 커밋합니다.

AI가 제가 모르는 사이에 제 원장을 수정할 수 있나요?

파일 편집은 AI 클라이언트가 무엇을 변경하는지에 대한 설명과 함께 editLedgerFiles를 호출하도록 요구합니다. (Claude Code를 포함한) 잘 동작하는 MCP 클라이언트는 실행하기 전에 이것을 여러분에게 표시합니다. 편집은 또한 아무것도 작성하지 않고 정확한 변경 사항을 미리 보여주는 dry_run 모드를 지원하므로, 클라이언트가 먼저 여러분에게 diff를 보여줄 수 있습니다. 그리고 커밋된 모든 변경은 원장 저장소의 실제 git 커밋이므로, 여러분은 완전한 감사 추적을 갖게 되고 표준 git 도구로 무엇이든 되돌릴 수 있습니다.

제 데이터가 제3자에게 전송되나요?

여러분의 원장 데이터는 (이미 여러분의 원장을 관리하는) Web Beancount 백엔드를 통해 흐르고 구조화된 결과로 AI 클라이언트에 반환됩니다. 여러분이 사용하는 AI 모델(예: Claude)은 다른 모든 컨텍스트와 마찬가지로 도구 결과를 받습니다. MCP 서버는 AI 클라이언트의 대화가 이미 보유한 것 이상으로는 어떤 데이터도 저장하지 않습니다.

각 토큰이 원장 범위로 제한된다 — 그게 무슨 뜻인가요?

MCP 서버를 인가할 때, 여러분은 어떤 원장에 접근 권한을 부여할지 선택합니다. 그 세션은 해당 원장에만 접근할 수 있습니다. 원장이 여러 개라면, 별도의 세션을 인가합니다. 이는 피해 범위를 제한합니다: 개인 원장을 위한 세션은 여러분의 비즈니스 원장을 건드릴 수 없습니다.

MCP 서버는 Fava 웹 UI가 실행 중이어야 하나요?

아니요. MCP 서버는 Web Beancount 인프라가 관리하는 내부 Fava API와 통신합니다(Fava는 여러분의 beancount.io 원장을 구동하는 웹 인터페이스입니다). Fava UI를 열어두거나 접근 가능하게 할 필요가 없습니다.

제 MCP 접근 권한을 취소하면 어떻게 되나요?

진행 중인 MCP 세션은 다음 도구 호출에서 401 오류를 받게 됩니다. OAuth 2.1을 지원하는 클라이언트는 자동으로 재인가를 시도하며, 여러분에게 다시 로그인하도록 요청합니다.

내부 동작

기술적으로 궁금한 분들을 위해 — 서버가 어떻게 구축되었는지.

AI 도구별로 자체 API/플러그인을 구축하는 대신 왜 MCP인가요?

MCP는 떠오르는 표준이며 이미 모든 주요 AI 에디터가 지원합니다. 규격을 준수하는 MCP 서버 하나를 구축하면 Claude, Cursor, Windsurf, 그리고 다음 분기에 출시될 무엇이든에 대한 별도의 통합을 유지하는 것과 달리, 전체 생태계와의 호환성을 한 번에 얻습니다. 프로토콜이 발견, 도구 스키마, 스트리밍을 처리하므로 — 우리는 도메인 로직에 집중합니다.

정적 API 키 대신 왜 OAuth 2.1인가요?

PKCE를 사용한 OAuth 2.1은 MCP 사양이 원격 서버에 권장하는 것이며, Claude Code 같은 클라이언트가 기본으로 구현하는 것입니다. 실질적 이점: 사용자는 토큰을 결코 만지지 않습니다. 클라이언트는 우리의 .well-known/oauth-protected-resource 메타데이터 엔드포인트를 통해 인가 서버를 발견하고, PKCE를 완료하며, 갱신을 자동으로 관리합니다. 정적 토큰은 전체 흐름을 구현하지 않은 클라이언트를 위한 대체 수단으로 계속 지원됩니다.

SSE나 stdio 전송 대신 왜 Streamable HTTP인가요?

Streamable HTTP는 HTTPS를 통한 원격 서버를 위해 설계된 MCP 전송입니다. Stdio는 로컬 프로세스를 위한 것입니다. SSE(더 오래된 MCP 전송)는 Streamable HTTP를 위해 폐기되고 있습니다. 우리 사용자는 우리 서버와 같은 위치에 있지 않은 AI 클라이언트에서 연결하므로, Streamable HTTP가 올바르고 미래 지향적인 선택입니다.

왜 MCP 세션이 상태 비저장(sessionIdGenerator 없음)인가요?

우리는 각 요청을 완전히 상태 비저장으로 만들기 위해 sessionIdGenerator: undefined를 설정합니다 — 도구 호출 사이에 서버 측 세션 상태가 할당되거나 유지되지 않습니다. 이것은 Streamable HTTP 사양의 상태 비저장 모드와 일치하며 세션 어피니티 없이 서버를 수평으로 확장 가능하게 유지합니다. 도구 컨텍스트(원장 신원, Fava API 클라이언트)는 검증된 OIDC 토큰으로부터 요청마다 재구성됩니다.

원장 접근 검증은 어떻게 작동하나요?

OIDC 토큰 검증 후, resolveLedgerAccess는 인증된 사용자가 요청된 원장에 실제로 접근 권한이 있는지 Fava API를 통해 확인합니다. 이것은 한 원장에 유효한 토큰이 다른 사용자의 원장을 탐색하는 데 사용되는 것을 방지합니다(서명된 토큰 위에 더해지는 심층 방어).

editLedgerFiles는 어디에 커밋하나요?

그것은 Fava API의 changeLedgerFiles를 호출하며, 이는 AI edit: <description> 메시지와 함께 원장의 Gitea 저장소에 git 커밋을 생성합니다. 설명은 AI가 채우는 description 필드에서 나오며 — 잘 동작하는 MCP 클라이언트에서는 실행 전에 사용자에게 표시됩니다.

editLedgerFiles의 dry_run 옵션은 무엇인가요?

dry_run: true는 모든 파일 작업을 검증하고(파일이 존재하는지 확인하고, str_replace의 이전 문자열이 정확히 한 번 일치하는지 확인) — 실제로 git에 작성하지 않고 — 무엇이 커밋될지 미리보기를 반환합니다. 이것은 커밋하기 전에 사용자에게 diff를 보여주고 싶은 AI 클라이언트에 유용합니다.

AI 클라이언트에 보이는 오류 표면은 무엇인가요?

도구 오류는 { isError: true, content: [{ type: "text", text: "..." }] }로 반환됩니다 — MCP SDK의 구조화된 오류 형식입니다. AI 클라이언트는 오류 메시지를 텍스트로 받고 어떻게 처리할지(재시도, 사용자에게 보고 등) 결정할 수 있습니다. HTTP 수준 인증 실패(401)에는 OAuth 보호 리소스 메타데이터를 가리키는 WWW-Authenticate 헤더가 포함되어, 규격을 준수하는 클라이언트가 인가 흐름을 자동으로 재개할 수 있습니다.