SDK
SDK를 사용하여 프로그래밍 방식으로 Claude Code를 애플리케이션에 통합하세요.
Claude Code SDK를 사용하면 개발자가 프로그래밍 방식으로 Claude Code를 애플리케이션에 통합할 수 있습니다. 이를 통해 Claude Code를 하위 프로세스로 실행하여 Claude의 기능을 활용하는 AI 기반 코딩 어시스턴트 및 도구를 구축할 수 있습니다.
SDK는 명령줄, TypeScript 및 Python 사용을 위해 제공됩니다.
인증
Claude Code SDK를 사용하려면 전용 API 키를 생성하는 것이 좋습니다:
- Anthropic 콘솔에서 Anthropic API 키를 생성합니다
- 그런 다음
ANTHROPIC_API_KEY
환경 변수를 설정합니다. 이 키를 안전하게 저장하는 것이 좋습니다(예: Github 시크릿 사용)
기본 SDK 사용법
Claude Code SDK를 사용하면 애플리케이션에서 비대화형 모드로 Claude Code를 사용할 수 있습니다.
명령줄
다음은 명령줄 SDK의 몇 가지 기본 예시입니다:
TypeScript
TypeScript SDK는 NPM의 메인 @anthropic-ai/claude-code
패키지에 포함되어 있습니다:
TypeScript SDK는 명령줄 SDK에서 지원하는 모든 인수와 함께 다음을 허용합니다:
인수 | 설명 | 기본값 |
---|---|---|
abortController | 중단 컨트롤러 | new AbortController() |
cwd | 현재 작업 디렉토리 | process.cwd() |
executable | 사용할 JavaScript 런타임 | Node.js로 실행 시 node , Bun으로 실행 시 bun |
executableArgs | 실행 파일에 전달할 인수 | [] |
pathToClaudeCodeExecutable | Claude Code 실행 파일 경로 | @anthropic-ai/claude-code 와 함께 제공되는 실행 파일 |
Python
Python SDK는 PyPI에서 claude-code-sdk
로 사용할 수 있습니다:
필수 조건:
- Python 3.10+
- Node.js
- Claude Code CLI:
npm install -g @anthropic-ai/claude-code
기본 사용법:
Python SDK는 ClaudeCodeOptions
클래스를 통해 명령줄 SDK에서 지원하는 모든 인수를 허용합니다:
고급 사용법
아래 문서는 명령줄 SDK를 예시로 사용하지만, TypeScript 및 Python SDK에서도 사용할 수 있습니다.
다중 턴 대화
다중 턴 대화의 경우, 대화를 재개하거나 가장 최근 세션에서 계속할 수 있습니다:
커스텀 시스템 프롬프트
Claude의 동작을 안내하기 위해 커스텀 시스템 프롬프트를 제공할 수 있습니다:
기본 시스템 프롬프트에 지시사항을 추가할 수도 있습니다:
MCP 구성
모델 컨텍스트 프로토콜(MCP)을 사용하면 외부 서버에서 추가 도구 및 리소스로 Claude Code를 확장할 수 있습니다. --mcp-config
플래그를 사용하여 데이터베이스 액세스, API 통합 또는 커스텀 도구와 같은 특수 기능을 제공하는 MCP 서버를 로드할 수 있습니다.
MCP 서버가 포함된 JSON 구성 파일을 생성합니다:
그런 다음 Claude Code와 함께 사용합니다:
MCP 도구를 사용할 때는 --allowedTools
플래그를 사용하여 명시적으로 허용해야 합니다. MCP 도구 이름은 mcp__<serverName>__<toolName>
패턴을 따릅니다. 여기서:
serverName
은 MCP 구성 파일의 키입니다toolName
은 해당 서버에서 제공하는 특정 도구입니다
이 보안 조치는 MCP 도구가 명시적으로 허용된 경우에만 사용되도록 합니다.
서버 이름만 지정하면(즉, mcp__<serverName>
), 해당 서버의 모든 도구가 허용됩니다.
글로브 패턴(예: mcp__go*
)은 지원되지 않습니다.
커스텀 권한 프롬프트 도구
선택적으로 --permission-prompt-tool
을 사용하여 사용자가 모델에게 특정 도구를 호출할 수 있는 권한을 부여하는지 확인하는 데 사용할 MCP 도구를 전달할 수 있습니다. 모델이 도구를 호출할 때 다음과 같은 일이 발생합니다:
- 먼저 권한 설정을 확인합니다: 모든 settings.json 파일과 SDK에 전달된
--allowedTools
및--disallowedTools
를 확인합니다. 이 중 하나가 도구 호출을 허용하거나 거부하면 도구 호출을 진행합니다 - 그렇지 않으면
--permission-prompt-tool
에 제공한 MCP 도구를 호출합니다
--permission-prompt-tool
MCP 도구에는 도구 이름과 입력이 전달되며, 결과가 포함된 JSON 문자열화된 페이로드를 반환해야 합니다. 페이로드는 다음 중 하나여야 합니다:
예를 들어, TypeScript MCP 권한 프롬프트 도구 구현은 다음과 같을 수 있습니다:
이 도구를 사용하려면 MCP 서버를 추가하고(예: --mcp-config
사용) 다음과 같이 SDK를 호출합니다:
사용 참고 사항:
updatedInput
을 사용하여 권한 프롬프트가 입력을 변경했음을 모델에 알립니다. 그렇지 않으면 위 예제와 같이updatedInput
을 원래 입력으로 설정합니다. 예를 들어, 도구가 사용자에게 파일 편집 차이를 보여주고 수동으로 차이를 편집하도록 허용하는 경우, 권한 프롬프트 도구는 업데이트된 편집을 반환해야 합니다.- 페이로드는 JSON 문자열화되어야 합니다
사용 가능한 CLI 옵션
SDK는 Claude Code에서 사용 가능한 모든 CLI 옵션을 활용합니다. SDK 사용을 위한 주요 옵션은 다음과 같습니다:
플래그 | 설명 | 예시 |
---|---|---|
--print , -p | 비대화형 모드로 실행 | claude -p "query" |
--output-format | 출력 형식 지정(text , json , stream-json ) | claude -p --output-format json |
--resume , -r | 세션 ID로 대화 재개 | claude --resume abc123 |
--continue , -c | 가장 최근 대화 계속하기 | claude --continue |
--verbose | 상세 로깅 활성화 | claude --verbose |
--max-turns | 비대화형 모드에서 에이전트 턴 제한 | claude --max-turns 3 |
--system-prompt | 시스템 프롬프트 재정의(--print 와 함께만 사용) | claude --system-prompt "Custom instruction" |
--append-system-prompt | 시스템 프롬프트에 추가(--print 와 함께만 사용) | claude --append-system-prompt "Custom instruction" |
--allowedTools | 허용된 도구의 공백으로 구분된 목록, 또는 쉼표로 구분된 허용된 도구 목록 문자열 | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | 거부된 도구의 공백으로 구분된 목록, 또는 쉼표로 구분된 거부된 도구 목록 문자열 | claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github" |
--mcp-config | JSON 파일에서 MCP 서버 로드 | claude --mcp-config servers.json |
--permission-prompt-tool | 권한 프롬프트 처리를 위한 MCP 도구(--print 와 함께만 사용) | claude --permission-prompt-tool mcp__auth__prompt |
CLI 옵션 및 기능의 전체 목록은 CLI 사용법 및 제어 문서를 참조하세요.
출력 형식
SDK는 여러 출력 형식을 지원합니다:
텍스트 출력(기본값)
응답 텍스트만 반환합니다:
JSON 출력
메타데이터를 포함한 구조화된 데이터를 반환합니다:
응답 형식:
스트리밍 JSON 출력
각 메시지를 수신할 때마다 스트리밍합니다:
각 대화는 초기 init
시스템 메시지로 시작하고, 사용자 및 어시스턴트 메시지 목록이 이어지며, 통계가 포함된 최종 result
시스템 메시지로 끝납니다. 각 메시지는 별도의 JSON 객체로 출력됩니다.
메시지 스키마
JSON API에서 반환된 메시지는 다음 스키마에 따라 엄격하게 타입이 지정됩니다:
곧 JSONSchema 호환 형식으로 이러한 타입을 게시할 예정입니다. 이 형식의 주요 변경 사항을 전달하기 위해 메인 Claude Code 패키지에 시맨틱 버전 관리를 사용합니다.
Message
및 MessageParam
타입은 Anthropic SDK에서 사용할 수 있습니다. 예를 들어, Anthropic TypeScript 및 Python SDK를 참조하세요.
예시
간단한 스크립트 통합
Claude로 파일 처리하기
세션 관리
모범 사례
-
프로그래밍 방식 응답 파싱을 위해 JSON 출력 형식 사용:
-
오류를 우아하게 처리 - 종료 코드 및 stderr 확인:
-
다중 턴 대화에서 컨텍스트를 유지하기 위해 세션 관리 사용
-
장시간 실행 작업에 대한 타임아웃 고려:
-
여러 요청을 할 때 호출 사이에 지연을 추가하여 속도 제한 준수
실제 응용 사례
Claude Code SDK를 사용하면 개발 워크플로우와 강력한 통합이 가능합니다. 주목할 만한 예시로는 Claude Code GitHub Actions가 있으며, 이는 SDK를 사용하여 GitHub 워크플로우에서 직접 자동화된 코드 리뷰, PR 생성 및 이슈 분류 기능을 제공합니다.
관련 리소스
- CLI 사용법 및 제어 - 전체 CLI 문서
- GitHub Actions 통합 - Claude로 GitHub 워크플로우 자동화
- 튜토리얼 - 일반적인 사용 사례에 대한 단계별 가이드