board의 청구·견적을 AI로 조작하는 MCP 서버를 만들었습니다 (비공식 OSS / TypeScript)

3줄 요약

클라우드 청구 관리 SaaS인 board를 Claude 등의 AI에게 말하여 조작할 수 있는 MCP 서버로 만들었습니다.
"이번 달 미입금 내역을 목록으로 보여줘"와 같은 한마디로 브라우저를 열 필요가 없습니다.
비공식 OSS (MIT).
npx @breakedge/the-board-mcp-server

로 즉시 테스트할 수 있습니다.

먼저 중요한 면책 사항

이 프로젝트는 board를 제공하는 Veru 주식회사와 제휴 또는 승인 관계가 없는, 완전한 비공식 OSS입니다. board®는 해당 회사의 상표입니다. 청구서·견적서 등의 재무 데이터를 다루는 도구이므로, 후술하는 바와 같이 기본값은 읽기 전용(Read-only)으로 설정되어 있으나, 이용은 자기 책임하에 부탁드립니다.

(참고로, Veru 주식회사 측에는 비공식 공개에 대해 미리 알려드렸습니다.)

월말, 청구서를 한 장씩 확인하는 것이 고되다

board는 견적·청구·발주 관련 기능이 강력한 클라우드 SaaS로, 중소기업이나 프리랜서의 "돈 관련 서류"를 일괄적으로 맡아주는 좋은 서비스입니다.

저희 회사에서도 일상적인 청구·견적에 board를 사용하고 있으며, 매달 도움을 받고 있습니다.

다만, 일상적인 확인 작업은 역시 수동으로 해야 합니다.

"이번 달 입금 예정인 건이 뭐였더라" → 화면을 열어 필터링하고...
"그 거래처 건, 얼마로 견적 냈었지" → 다시 검색하고...

이렇게 저희가 매달 반복하고 있는 작업을 AI에게 말해서 끝내고 싶었습니다. 요컨대 자신의 업무를 효율화하고 싶어서 만든 것이 이 MCP 서버입니다.

우선, 이렇게 사용할 수 있습니다

MCP 클라이언트 (Claude Desktop / Claude Code / Cursor / VS Code 등)에 연결하면 다음과 같은 대화가 가능합니다. 전체적인 구조는 단순합니다. 당신의 말을 AI가 받아들이고, MCP 서버를 통해 board를 조작한다——그것뿐입니다.

실제 주고받는 이미지(예시)는 다음과 같습니다.

장면 1: 입금 확인

당신: 이번 달 입금 예정인 청구서를 금액이 큰 순서대로 알려줘
AI: (청구서를 가져와 정리했습니다)
이번 달 입금 예정은 4건입니다.
...

화면을 열어 필터링하고 합계를 내는 과정이 통째로 한마디로 해결됩니다.

장면 2: 안건 정리

당신: 거래처 "◯◯"의 진행 중인 안건과, 연결된 견적 금액을 정리해줘
AI: ◯◯님의 진행 중인 안건은 3건, 견적 합계는 ¥2,200,000입니다.
내역과 각 안건의 상태는 다음과 같습니다 ...

장면 3: 대략적인 집계

당신: 지난달에 발행한 청구서, 합계가 얼마였지?
AI: 지난달 발행분은 12건, 합계 ¥5,940,000였습니다.

"Excel로 내보내 줘", "Slack용으로 불렛 포인트로 만들어 줘"와 같은 후속 가공까지 한꺼번에 부탁할 수 있는 점이 AI를 경유할 때의 즐거움입니다.

가장 효과적인 것은 「서류 작성」을 맡기는 것

솔직히 업무 효율화의 임팩트가 가장 큰 부분은 여기입니다. 플래그(Flag)를 하나 추가하는 것만으로 견적·청구서 작성까지 AI에게 맡길 수 있습니다. 매달 반복되는 정형적인 서류 작업이야말로 통째로 맡겼을 때의 이점이 큰 부분입니다.

당신: 지난달 "◯◯" 안건 내용으로 청구서를 만들어 둬
AI: (견적을 바탕으로 청구서 초안을 작성했습니다)
내용은 다음과 같습니다. 문제가 없다면 그대로 발행할 수 있습니다.

쓰기(Write) 작업은 안전을 위해 기본적으로 비활성화되어 있으며, 사용자가 직접 활성화(Opt-in)하는 방식으로 구성했습니다. 준비가 되었다면 설정에 플래그를 하나 추가하기만 하면 됩니다 (후술).

MCP란 무엇인가? (아는 분은 넘어가셔도 좋습니다)

한마디로 말하면, AI와 외부 도구·데이터를 연결하는 공통 규격입니다. MCP 서버를 하나 세워두면, 대응하는 AI 클라이언트에서 "도구(Tool)\

이렇게 재시작하면, 방금 전의 대화를 할 수 있는 상태가 됩니다.

쓰기(Write)도 시도해보고 싶은 분은 args에 플래그를 하나 추가합니다.

"args": ["-y", "@breakedge/the-board-mcp-server", "--enable-writes"]

"하지만, AI에게 돈 관련 데이터를 맡겨도 괜찮을까?"

이 부분이 가장 신경 쓰이시죠? 저도 만들면서 내내 신경 썼던 부분입니다. 답은 "기본적으로 '보기'만 가능하도록 설정했다" 입니다.

쓰기 작업은 3단계로 나누어져 있으며, 아무것도 설정하지 않으면 가장 안전한 레벨 0으로 동작합니다.

레벨	추가할 플래그	가능한 작업	초기 상태
0	(없음)	읽기 전용	현재 상태
1	`--enable-writes`	+ 생성·업데이트	OFF
2	`--enable-destructive-writes`	+ 삭제·상태 변경·잠금	OFF

핵심은 허가되지 않은 작업은 AI에게 "애초에 보이지 않는다"는 점입니다. 읽기 전용 모드에서는 AI의 도구(Tool) 목록에 '삭제'나 '생성'이라는 도구 자체가 나타나지 않습니다. 따라서 "AI가 실수로 청구서를 삭제하는 일"은 설계 단계에서부터 방지됩니다.

설계상의 포인트로, 가장 효율화할 수 있는 '생성·업데이트'(레벨 1)와 더 신중하게 다뤄야 할 '삭제'(레벨 2)를 별개의 스위치로 분리했습니다. 즉, "서류 작성은 AI에게 맡기되, 삭제는 직접 하겠다"라는 중간 설정을 선택할 수 있다는 뜻입니다. 개인적으로는 레벨 1부터 시작하는 것을 추천합니다.

나아가, 명시적으로 "읽기 전용으로"라고 지정할 경우에는 최우선 안전장치로 취급하여, 다른 허가 플래그가 함께 설정되어 있더라도 쓰기 권한을 무효화합니다 (fail-closed). 또한 board API의 레이트 리밋 (Rate Limit)에 맞춘 폭주 방지 요청 제어도 포함되어 있습니다.

구조 이야기 (궁금한 분들을 위해)

여기서부터는 구현에 관한 이야기입니다. "그냥 쓸 수 있으면 된다" 하시는 분들은 다음 헤드라인까지 건너뛰셔도 좋습니다.

board API는 v1.6.0 기준으로 89개의 엔드포인트 (Endpoint)가 있습니다. 이를 하나씩 도구화하면 개수가 폭발적으로 늘어나 AI의 도구 선택이 힘들어집니다.

그래서 freee-mcp에서도 사용되는 Generic REST Tools 패턴을 채택했습니다. 엔드포인트 단위가 아니라 HTTP 메서드 단위의 범용 도구 6개로 모든 것을 처리합니다.

도구	역할
`the_board_api_get`	조회 (단일 / 목록)
`the_board_api_post`	생성
`the_board_api_patch`	업데이트 · 상태 변경 · 잠금
`the_board_api_delete`	삭제
`the_board_api_list_paths`	엔드포인트 검색
`the_board_auth_status`	인증 · 남은 요청 수 확인

열쇠는 OpenAPI 스키마 (Schema) 구동 방식입니다. board API의 최소 스키마를 서버에 동봉하여, AI는 먼저 list_paths로 사용할 수 있는 경로를 찾고, get 등으로 호출합니다. 호출 시에는 해당 경로가 스키마에 존재하는지 검증합니다. 엔드포인트가 늘어나더라도 스키마 업데이트만으로 대응할 수 있으며, 도구는 6개로 유지됩니다.

보안 측면에서는 경로 탐색 (Path Traversal) 거부, CRLF 제거, /v1/ 강제 적용과 더불어, 에러 응답에서 인증 헤더나 토큰 값을 삭제한 뒤 AI에게 반환하도록 했습니다 (auth_status 역시 토큰 값 자체는 반환하지 않습니다).

향후 계획 및 피드백

현재는 Beta (0.x) 단계입니다. API가 안정화되면 v1.0을 목표로 합니다. Streamable HTTP Transport 지원도 수요가 있다면 해볼까 생각 중입니다.

비공식 프로젝트이므로 외부에서의 PR (Pull Request)은 받지 않지만, 요청이나 버그 제보는 GitHub Issue를 통해 언제든 환영합니다. "board의 이 작업을 AI에게 통째로 맡기고 싶다" 하는 것이 있다면 꼭 알려주세요.

마치며

「업무 SaaS × AI」는 앞으로 당연해질 영역이라고 생각합니다. 그중에서도 board와 같이 "돈과 관련된 업무"를 다루는 툴은 편리함만큼이나 안전성이 요구됩니다. 본 서버가 그 양립의 한 사례가 될 수 있다면 기쁘겠습니다.

만약 당신의 회사에서도 board를 사용하고 있다면, 청구 및 경리를 담당하는 동료에게 "AI로 이런 것을 할 수 있어"라고 알려주세요.

매일 board를 사용하는 사람일수록 어느 부분이 편해질지 상상하기 쉬울 것이기 때문입니다.

한번 시도해 보시고 GitHub의 ⭐(Star)나 감상을 남겨주신다면, 다음 작업을 이어갈 힘이 됩니다.