SDK
SDKを使用してClaude Codeをプログラムでアプリケーションに統合します。
Claude Code SDKを使用すると、開発者はClaude Codeをプログラムでアプリケーションに統合できます。これにより、Claude Codeをサブプロセスとして実行し、Claudeの機能を活用したAIパワードのコーディングアシスタントやツールを構築する方法を提供します。
SDKはコマンドライン、TypeScript、Pythonでの使用が可能です。
認証
Claude Code SDKを使用するには、専用のAPIキーを作成することをお勧めします:
- Anthropic Consoleで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 "クエリ" |
--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 "カスタム指示" |
--append-system-prompt | システムプロンプトに追加(--print でのみ) | claude --append-system-prompt "カスタム指示" |
--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ワークフローを自動化
- チュートリアル - 一般的なユースケースのステップバイステップガイド