bokio-mcp

Bokio 회계 API를 위한 MCP 서버입니다. 하나의 Bokio 회사에 대해 85개의 도구를 제공합니다 — 송장, 고객, 공급업체, 공급업체 송장, 분개장, 대변 메모, 계정과목표, 회계연도, 품목, 태그, 업로드, SIE 내보내기 및 은행 결제 — 따라서 MCP 클라이언트는 장부를 읽고 (선택적으로) 쓸 수 있습니다.

계정도, 데이터베이스도, 호스팅 서비스도 없습니다. 서버 인스턴스당 하나의 회사만 처리합니다.

"Which invoices are still unpaid?"
"Book the attached receipt against account 6570."
"Export the SIE file for the 2025 fiscal year."

빠른 시작

Bokio 계정 없이 픽스처로 시도해 보세요:

BOKIO_MOCK=true npx bokio-mcp status
# { "companyName": "Testbolaget AB", "status": "active", ... }

BOKIO_MOCK=true는 프로세스 내 가짜 Bokio를 제공하므로 자격 증명이 없어도 전체 도구 표면이 작동합니다.

실제 데이터를 사용하려면 아래 두 자격 증명 경로 중 하나를 선택하고 MCP 클라이언트에 서버를 추가하세요.

경로 A — 프라이빗 통합 토큰 (권장)

Bokio에서: 회사 설정 → 통합 → API 토큰 → 프라이빗 통합 만들기. 토큰은 수명이 길고 해당 회사 하나에만 범위가 지정되며 OAuth 검토가 필요 없습니다.

{
  "mcpServers": {
    "bokio": {
      "command": "npx",
      "args": ["-y", "bokio-mcp"],
      "env": {
        "BOKIO_INTEGRATION_TOKEN": "your-token",
        "BOKIO_COMPANY_ID": "the-company-uuid-from-the-bokio-url"
      }
    }
  }
}

경로 B — OAuth

리디렉션 URI http://127.0.0.1:7337/callback로 Bokio 개발자 포털에 통합을 등록한 다음:

export BOKIO_CLIENT_ID=... BOKIO_CLIENT_SECRET=...
npx bokio-mcp login

그러면 브라우저에서 Bokio가 열리고 토큰이 ~/.config/bokio-mcp/tokens.json (모드 0600)에 기록됩니다. 액세스 토큰은 자동으로 갱신되며, 리프레시 토큰 회전도 포함됩니다. MCP 클라이언트를 동일한 두 환경 변수로 npx -y bokio-mcp에 지정하세요.

Related MCP server: QuickBooks Online MCP Server

쓰기는 기본적으로 꺼져 있음

새로 설치하면 읽기만 가능하고 쓰기는 불가능합니다. 변경 도구는 단순히 차단되는 것이 아니라 tools/list에서 존재하지 않습니다. 따라서 모델은 수행할 수 없는 편집을 제안하지 않습니다:

BOKIO_ALLOW_WRITES=true

85개 도구 중 38개는 읽기 전용이고 47개는 변경 작업입니다. 플래그 없이 시작하고, 모델이 예상한 대로 읽고 있는지 확인한 다음 쓰기를 켜세요.

명령어

HTTP 전송

예를 들어 리버스 프록시나 컨테이너 뒤에서 자체 호스팅하는 경우:

MCP_AUTH_TOKEN=$(openssl rand -hex 32) bokio-mcp serve --http

그러면 /mcp는 해당 정적 bearer로 보호됩니다. MCP_AUTH_TOKEN이 없으면 서버는 인증되지 않은 브리지를 실시간 회계 데이터에 노출하는 대신 127.0.0.1에만 바인딩됩니다. Dockerfile이 포함되어 있으며 기본적으로 이 전송을 사용합니다.

환경

주석이 달린 버전은 .env.example을 참조하세요.

토큰 저장에 관한 참고 사항

OAuth 토큰 파일은 BOKIO_TOKEN_ENCRYPTION_KEY가 설정되지 않은 경우 모드 0600의 일반 텍스트입니다 — gh 및 aws CLI와 동일한 자세입니다. 개인 머신에서는 암호화하는 것 옆에 저장된 키가 거의 추가되지 않습니다. 파일이 컨테이너 이미지나 공유 호스트처럼 덜 사적인 곳에 있을 때 설정하세요.

개발

npm install
npm test          # 36 tests, no database, no credentials
npm run typecheck
npm run dev       # tsx watch, stdio transport

BOKIO_MOCK=true는 모든 Bokio 요청을 fetch 계층에서 프로세스 내 목(mock)으로 라우팅하므로 stdio, HTTP, 그리고 서버가 실행되지 않는 테스트에서도 동일하게 동작합니다. test/mcp.test.ts는 실제 MCP 프로토콜을 종단 간으로 구동합니다.

도구 정의는 src/tools/bokio/에 수기로 작성되지만, 각 도구의 경로와 메서드는 op() 헬퍼에 의해 컴파일 시점에 OpenAPI 사양과 대조됩니다 — 경로의 오타는 빌드를 실패시킵니다. 사양 유형을 다시 생성하려면:

npm run gen:bokio

지원되지 않는 기능

• 인스턴스당 둘 이상의 회사. Bokio 자격 증명은 회사별입니다. 두 번째 회사는 두 번째 인스턴스를 실행하세요.

• 상승된 범위. bank-payments:*는 Bokio의 통합별 승인이 필요합니다. 은행 결제 도구는 등록되지만 통합이 승인되고 범위가 BOKIO_SCOPES에 추가될 때까지 실패합니다.

라이선스

MIT