AI 에이전트에 최적화된 kintone CLI 도구 「kintone-cli」를 공개했습니다

AI 에이전트의 이용을 전제로 설계한, kintone REST API의 커맨드 라인 도구(CLI tool)를 공개했습니다.

최근 많은 kintone 관리자와 개발자분들이 AI 에이전트에 kintone MCP 서버를 설정하여 일상 업무에 활용하고 계실 것이라 생각합니다.

한편, 2026년 3월경 MCP에 대해 CLI 도구의 우위성을 주장하는 논조가 고조되었던 시기가 있었습니다.

이 기사에 그 경위가 알기 쉽게 정리되어 있습니다.

저 자신은 사이보우즈(Cybozu) 공식 kintone MCP 서버를 편리하게 사용해 왔으나, 다음과 같은 점들이 조금 신경 쓰였습니다.

• 컨텍스트(Context) 소비가 크다

• 대량 데이터를 읽어오면 컨텍스트를 한꺼번에 압박한다

• 레코드 취득 시의 페이지네이션(Pagination)에 대응하지 않는다

• 커버하는 엔드포인트(Endpoint)가 제한적이다

그러던 중, AI 에이전트를 퍼스트 클래스(First-class) 유저로 취급하는 CLI 설계 지침을 정중하게 해설한 블로그 기사를 만났습니다. 기사의 원저자분은 그 지침에 따라 Google Workspace의 CLI를 개발하고 계십니다.

그 기사에 자극을 받아, kintone의 CLI를 만들어 보고 싶다고 생각한 것이 개발 동기입니다. 조금씩 수정하며 도그푸딩(Dogfooding)을 해본 결과, 나름대로 쓸만한 것이 완성되어 공개를 결정하게 되었습니다.

참고로, 사이보우즈 공식 cli-kintone은 개발자용 실용 도구 세트입니다. 본 도구(kintone-cli)는 kintone REST API의 엔드포인트를 AI 에이전트가 다루기 쉬운 형태로 공개하는 것을 목적으로 하고 있어, 대상 범위와 용도가 다릅니다.

여기서는 설계 컨셉의 핵심을 3가지 경험으로 압축하여 소개합니다. 모두 「AI 에이전트가 효율적이고 안전하게 kintone을 조작하기」 위한 장치입니다.

kintone을 AI 에이전트에서 다룰 때, 컨텍스트 소비는 「읽는 쪽」과 「쓰는 쪽」 모두에서 커지기 쉽습니다. 레코드를 취득하면 응답 JSON이 컨텍스트에 실리게 되고, 복합 호출을 수행하는 경우에는 큰 페이로드(Payload)를 자신의 출력 토큰(Output Token)으로 생성해야 합니다.

MCP는 기본적으로 둘 다 「대화 속」을 통하도록 설계되어 있지만, kintone-cli는 그 양쪽 모두를 「대화 밖」으로 빼내는 루트를 제공합니다.

kintone REST API를 통한 레코드 취득은 1 요청당 최대 500건이며, 대량 데이터를 다룰 때는 페이지네이션이 필수입니다. MCP를 통하면 전 건을 에이전트의 컨텍스트에 실을 수밖에 없어 쉽게 윈도우(Window)를 압박합니다.

records get --page-all은 내부에서 커서(Cursor) API를 사용하여 전 건을 취득하고, 1 레코드 1행의 NDJSON으로서 표준 출력으로 스트리밍(Streaming)합니다.

$ kt records get --app 42 --fields "Title,Status" --page-all
{"Title":{"value":"見積依頼 A"},"Status":{"value":"open"}}
{"Title":{"value":"見積依頼 B"},"Status":{"value":"closed"}}
...

NDJSON은 Unix의 전통적인 파이프라인(Pipeline)에 태울 수 있습니다. 중간에 필터링하거나 건수를 제한하는 등의 가공을 에이전트의 컨텍스트를 거치지 않고 수행할 수 있습니다.

# 중간에 필터링
kt records get --app 42 --page-all | jq 'select(.Status.value == "open")'
# 선두 100건만 보기
...

AI 에이전트가 이 부분을 자율적으로 판단하여, 명령어를 조합함으로써 목적의 데이터에 효율적으로 도달해 줍니다.

큰 페이로드를 보내는 쪽에서는 --json @path를 사용할 수 있습니다 (curl -d @file.json과 동일한 규약).

# 에이전트는 일단 파일로 내려받은 후, 경로만 전달한다
kt bulk-request add --json @/tmp/payload.json

포인트는 JSON 본체가 에이전트의 출력 토큰을 통과하지 않는다는 점입니다. MCP를 경유하는 경우, 에이전트는 tool_use의 인자로서 큰 JSON을 스스로 생성 및 출력해야 합니다.

파일 참조라면, 일단 Write

/tmp/payload.json에 써두기만 하면, 이후 kt 호출 시 인자는 경로 문자열뿐입니다.

이는 셸 인자의 OS 제한(ARG_MAX, macOS의 경우 약 1MB)에도 걸리지 않습니다.

두 가지가 갖춰지면, 에이전트는 입출력을 디스크로 연결하는 처리를 스스로 구성할 수 있게 됩니다. 예를 들어 사용자로부터 다음과 같은 지시가 내려왔다고 가정해 봅시다.

"앱 42의 Vendor 필드가 Acme Inc인 레코드를 모두 Acme LLC로 업데이트해 주세요."

에이전트는 대체로 다음과 같은 명령줄을 구성합니다 (생성되는 코드는 상황에 따라 달라집니다).

# 1. 전체 데이터를 디스크에 저장 (응답은 컨텍스트를 경유하지 않음)
kt records get --app 42 --fields '$id,Vendor' --page-all > /tmp/r.jsonl
# 2. jq로 필터링하여 업데이트 페이로드(payload)로 재구성 (중간 데이터도 컨텍스트를 경유하지 않음)
...

여기서 에이전트의 대화 이력(conversation history)에 남는 것은 지시 사항과 메타데이터뿐입니다. 레코드의 내용은 디스크 상에서 오가며 컨텍스트에는 포함되지 않습니다. /tmp가 에이전트의 외부 메모리(external memory)처럼 기능하고 있는 것입니다.

쓰기 계열의 작업은 되돌리는 비용이 높기 때문에, "실행 전에 로컬에서 멈추기" 위한 메커니즘을 두 가지 준비했습니다.

쓰기 계열 명령에 --dry-run을 붙이면, HTTP 요청을 보내지 않고 전송하려는 메서드(method), 경로(path), 바디(body)를 JSON으로 출력합니다.

$ kt record add --json '{"app":1,"record":{"name":{"value":"hello"}}}' --dry-run
{
"dryRun": true,
...

AI 에이전트가 이 CLI를 사용하고 있으면, 쓰기 계열의 작업을 수행해야 하는 상황에서 자발적으로 "먼저 --dry-run을 시도해 볼까요?"라고 물어봐 줍니다. 명시적으로 요청하지 않아도 안전한 방향으로 판단해 주므로 안심할 수 있습니다.

--json을 받는 명령에서는 전송 전에 로컬에서 OpenAPI 스키마(schema)와 대조하여 페이로드를 검사합니다. AI 에이전트가 생성한 JSON에는 오타(typo)가 포함될 수 있지만, API에 전송하여 에러 응답을 받기 전에 로컬에서 체크할 수 있다면 토큰(token) 낭비와 kintone의 레이트 리밋(rate limit) 소비를 피할 수 있으며, 체감 속도도 저하시키지 않을 수 있습니다.

$ kt record add --json '{"app":1,"rcord":{"name":{"value":"x"}}}'
{"error":"json_validation_failed","method":"POST","path":"/k/v1/record.json",
"errors":[
...

위의 예시에서는 최상위 키인 record가 rcord로 잘못 입력된 것을 API 호출 전에 감지합니다. 에이전트는 기계 판독 가능한(machine-readable) 에러를 읽고, missingProperty: "record"와 additionalProperty: "rcord"를 통해 "아, record를 rcord로 잘못 썼구나"라고 스스로 판단하여 출력을 수정합니다.

이 두 가지는 독립적인 메커니즘이지만, --dry-run 실행 시에도 유효성 검사(validation)는 수행됩니다. 즉, "전송하지 않고 페이로드의 구문(syntax)도 검사한다"는 작업이 한 번의 명령으로 완결됩니다.

앞 절에서 소개한 --json 유효성 검사는 패키지에 동봉된 OpenAPI 스키마를 내부적으로 사용합니다. 이 동일한 스키마를 에이전트가 직접 읽어올 수 있도록 만든 것이 --schema 옵션입니다. 각 엔드포인트(endpoint) 명령에 --schema를 붙이기만 하면 해당 오퍼레이션(operation)의 정의가 JSON으로 반환됩니다.

$ kt record add --schema | jq .operation.requestBody
{
"required": true,
...

• 인증 정보나 KINTONE_BASE_URL도 필요 없음 - 네트워크 액세스도 하지 않음
• 에이전트는 즉시 "올바른 인자 형태"를 파악할 수 있음

"API에 대한 것은 API에게 물어본다"는 원칙을 네트워크를 통하지 않고 로컬에서 완결시켰다는 것이 핵심입니다.

여기서는 최소한의 설정 방법을 소개합니다.

# 설치 (Node.js 22+)
npm install -g @yoshkosh/kintone-cli
# 인증 정보를 환경 변수로
...

설치 후에는 kt를 사용하거나, kintone-cli를 사용해도 동일한 것을 실행할 수 있습니다. 본 기사에서는 짧은 kt를 사용하고 있습니다.

설정 파일은 필요하지 않으며, 인증 정보는 환경 변수만으로 지정합니다. 따라서 CI, 컨테이너, AI 에이전트 실행 환경 중 어디에서든 추가 설정 없이 바로 사용할 수 있습니다.

AI 에이전트에서 사용하는 경우, 사용법을 해설한 agentskills.io 규격 준수의 스킬 정의(skill definition)를 동봉하고 있습니다. npx skills로 등록하면, 에이전트는 이 스킬 정의를 참조하면서 kintone-cli를 사용할 수 있게 됩니다.

# Claude Code 예시
npx skills add https://github.com/yoshkosh/kintone-cli -g -a claude-code -y

저 자신은 일상적인 개발 작업에서 Claude Code를 사용하고 있지만, kintone에 대한 액세스는 대체로 이 도구로 해결하고 있습니다. --page-all의 NDJSON 스트림이나 --json @path의 파일 참조를 사용하고 싶은 상황이 많기 때문입니다.

또한, 앱이나 레코드 권한 설정 변경 등 MCP가 커버하지 않는 엔드포인트(endpoint)의 조작에도 사용할 수 있다는 점이 장점 중 하나입니다.

그렇기는 하지만, AI 에이전트의 데스크톱 앱(Claude Desktop 등)에서는 MCP만 사용할 수 있으며, 무엇보다 kintone MCP 서버는 사이보우즈(Cybozu) 공식 제품이라 안심감이 있습니다.

kintone을 AI 에이전트에서 다룰 때의 선택지 중 하나로서, 이 기능과 특성을 활용할 수 있는 상황이 있다면 시도해 주시면 감사하겠습니다.