space ocr Claude 스킬: 문서를 구조화된 조회 가능 데이터로

space ocr 스킬이란

space ocr 은 Claude Code 에 설치하는 플러그인 형태의 Claude 스킬이다. 설치해 두면 Claude 가 송장·영수증·명함·신분증·각종 양식 같은 문서 이미지를 구조화된 필드로 바꿔 줄 수 있게 된다. 내부적으로는 space ocr REST API(https://api.space-ocr.com)를 호출한다.

흔히 하는 "이미지를 붙여 넣고 모델이 잘 읽기를 기대하는" 방식과는 성격이 다르다. 붙여 넣기 방식은 값이 어디서 왔는지 알 수 없고, 모델이 숫자를 그럴듯하게 지어낼 수 있으며, 처리한 결과가 어디에도 남지 않는다. space ocr 은 추출한 모든 값에 문서상 정확한 위치(바운딩 박스) 를 함께 돌려주고, 처리한 문서를 API 뒤편의 조회 가능한 작업공간(폴더 / 시트 / 행)에 그대로 보관한다.

반대로, OCR 엔진을 직접 띄우고 그 결과를 담을 데이터베이스나 벡터 스토어를 따로 구축하는 방식과도 다르다. space ocr 에서는 시트를 만들고 이미지를 올리면 행(row)이 API 뒤에 쌓인다. 별도 DB·인덱싱 인프라 없이 추출과 보관, 조회가 한 곳에서 끝난다.

설치

설치는 한 번만 하면 된다. Claude Code 안에서 슬래시 명령 두 줄을 실행한다. 첫 줄은 스킬이 들어 있는 마켓플레이스를 등록하고, 둘째 줄은 그 마켓플레이스에서 스킬을 설치한다.

설치가 끝나면 이후로는 Claude Code 가 알아서 이 스킬을 사용할 수 있다. 런타임은 표준 라이브러리만 쓰는 파이썬 스크립트 하나(scripts/space_ocr.py)뿐이다. pip install 도, MCP 서버도, 별도 SDK 도 필요 없고 python3 만 있으면 된다. 모든 명령의 출력은 stdout 에 JSON 으로 나온다.

준비 — API 키와 balance 확인

API 키는 https://space-ocr.com 에서 로그인한 뒤 Settings → API Keys 에서 발급한다. 가입 시 무료 스캔 100회가 주어지며 카드 등록은 필요 없다.

키는 환경변수 SPACE_OCR_API_KEY=spocr_... 로 넣거나 .env 파일에 둔다. API 인증은 Authorization: Bearer spocr_... 헤더로 이뤄지고, 기본 베이스 URL 은 https://api.space-ocr.com 이다(필요하면 SPACE_OCR_API_BASE 로 덮어쓸 수 있다).

키를 넣은 다음 balance 한 줄로 동작을 확인한다. 출력에는 무료 잔여분(free.remaining), 정액(flatfee), 유료 잔액이 함께 나온다. 조회(balance, view, query)는 스캔을 소비하지 않는다(0회).

문서 한 장 처리

이미지 한 장에서 필드를 뽑을 때는 ocr 명령에 내장 템플릿을 지정한다. 예를 들어 송장이라면 --template invoice 를 쓴다.

내장 템플릿 id 에는 invoice, receipt, business_card, purchase_order, delivery, quote, bankbook, passport, driver_license, resident_card, my_number_card, residence_card 가 있다.

내장 템플릿에 없는 문서라면 두 가지 선택지가 있다. 직접 정의한 스키마 파일을 --fields <schema.json> 으로 넘기거나, --auto 로 엔진이 필드 4~8개를 추론하게 둔다. --auto 에는 거부 게이트가 있어서, 구조가 없거나 빈 이미지·풍경 사진처럼 추출할 게 없는 입력은 필드를 지어내지 않고 에러를 반환하며 해당 스캔은 자동 환불된다.

한 번의 OCR 호출은 정확히 1 스캔을 소비한다. 실패한 스캔은 자동으로 환불된다. 같은 작업을 재시도할 때는 Idempotency-Key 를 함께 보내면 같은 키에 대해 캐시된 결과를 그대로 돌려주므로 중복 과금이 없다.

폴더 단위 처리 → 시트

문서가 여러 장이면 결과를 시트에 모은다. 순서는 두 단계다.

먼저 컬럼을 한 번 정의해 두고 시트를 만든다. create sheet <PATH> <NAME> --columns columns.json 으로 만들면, create 가 반환하는 uniqueKey 경로(예: /invoices/8G90wq...)를 받게 된다. 여기서 주의할 점이 있다. 폴더는 이름으로 주소를 잡지만(/invoices), 시트나 메모는 표시 이름이 아니라 이 uniqueKey 경로로만 가리킨다. 반환된 경로를 잘 보관해 두고 이후 명령에 그대로 재사용해야 한다.

시트가 만들어지면 이미지를 한꺼번에 올린다. OCR 은 서버 쪽에서 비동기로 돌아간다. --wait 를 붙이면 모든 처리가 끝날 때까지 명령이 블록된다. (--wait 없이 올린 뒤 반환된 JOB_ID 를 job <JOB_ID> 로 폴링해도 된다.)

업로드한 이미지 한 장은 OCR 호출과 마찬가지로 각각 1 스캔을 소비한다.

저장된 행에서 질문에 답하기

문서가 일단 시트에 들어가면, 거기에 대한 질문은 다시 OCR 하지 말고 저장된 행을 조회해서 답한다. query <SHEET> 에 서버 측 필터·정렬·제한을 붙인다.

• --where 'total>=40000' — 서버에서 조건으로 행을 거른다
• --sort total:desc — 서버에서 정렬한다
• --limit 20 — 반환 행 수를 제한한다

조회는 무료(0 스캔)다. 같은 시트를 몇 번이고 다른 조건으로 질의해도 스캔이 소비되지 않는다. 필터링·정렬을 클라이언트로 끌고 와서 처리하지 말고 query 의 인자로 서버에 맡기면 된다. (시트가 아닌 폴더/경로를 그대로 훑어볼 때는 view <PATH> 에 같은 --where/--sort/--limit 를 쓸 수 있다.)

가볍고 신뢰할 수 있게 유지하는 네 가지 규칙

이 스킬의 동작을 규정하는 네 가지 규칙이 있다. 이를 지키면 스캔 소비가 줄고 결과를 검증할 수 있게 된다.

1. 쌓되, 토해내지 말 것(Store, don't dump) — 문서가 한 장을 넘어가면 원본 OCR JSON 을 그대로 되붙이지 말고 시트에 행으로 기록한다.
2. 스캔 전에 확인(Check before you scan) — 배치 전에 balance 를 한 번 돌린다. 이미 행으로 들어가 있는 문서는 다시 스캔하지 말고 기존 행을 재사용한다.
3. 저장된 행으로 답하기(Answer from stored rows) — 질문에는 query <sheet> 와 서버 측 --where/--sort/--limit 로 답한다. 조회는 무료이고, 다시 OCR 하지 않는다.
4. 위치를 인용하고 불확실성을 표시(Cite the location, flag uncertainty) — 모든 값에는 field_bboxes 위치가 붙는다. 값은 인쇄된 그대로 그대로 추출하는 편이 좋다. 임의로 정규화하거나 계산해서 바꾸면 박스가 어긋난다.

참고 — 스캔(quota) 모델 한눈에

과금 단위는 단순하다. OCR 호출 1건 또는 업로드 이미지 1장 = 정확히 1 스캔이다. 조회(view/query)는 0 스캔이다. 실패한 스캔은 자동 환불되고, --auto 거부 게이트에 걸린 입력도 환불된다. 재시도 시 Idempotency-Key 를 동일하게 보내면 캐시된 결과를 재생해 중복 과금을 막는다. balance 는 무료 잔여분·정액·유료 잔액을 합쳐 보여 준다.