Claude Code SDKを使用すると、開発者はClaude Codeをプログラムでアプリケーションに統合できます。これにより、Claude Codeをサブプロセスとして実行し、Claudeの機能を活用したAIパワードのコーディングアシスタントやツールを構築する方法を提供します。

SDKはコマンドライン、TypeScript、Pythonでの使用が可能です。

認証

Claude Code SDKを使用するには、専用のAPIキーを作成することをお勧めします:

  1. Anthropic ConsoleでAnthropic APIキーを作成します
  2. 次に、ANTHROPIC_API_KEY環境変数を設定します。このキーは安全に保管することをお勧めします(例:Githubのシークレットを使用)

基本的なSDKの使用方法

Claude Code SDKを使用すると、アプリケーションから非インタラクティブモードでClaude Codeを使用できます。

コマンドライン

コマンドラインSDKの基本的な例をいくつか紹介します:

# 単一のプロンプトを実行して終了(プリントモード)
$ claude -p "フィボナッチ数を計算する関数を書いてください"

# パイプを使用して標準入力を提供
$ echo "このコードを説明してください" | claude -p

# メタデータを含むJSON形式で出力
$ claude -p "hello world関数を生成してください" --output-format json

# 到着したJSONをストリーミング出力
$ claude -p "Reactコンポーネントを構築してください" --output-format stream-json

TypeScript

TypeScript SDKは、NPMの主要な@anthropic-ai/claude-codeパッケージに含まれています:

import { query, type SDKMessage } from "@anthropic-ai/claude-code";

const messages: SDKMessage[] = [];

for await (const message of query({
  prompt: "foo.pyについての俳句を書いてください",
  abortController: new AbortController(),
  options: {
    maxTurns: 3,
  },
})) {
  messages.push(message);
}

console.log(messages);

TypeScript SDKは、コマンドラインSDKでサポートされているすべての引数に加えて、以下の引数も受け付けます:

引数説明デフォルト
abortControllerアボートコントローラーnew AbortController()
cwdカレントワーキングディレクトリprocess.cwd()
executable使用するJavaScriptランタイムNode.jsで実行する場合はnode、Bunで実行する場合はbun
executableArgs実行可能ファイルに渡す引数[]
pathToClaudeCodeExecutableClaude Code実行可能ファイルへのパス@anthropic-ai/claude-codeに同梱されている実行可能ファイル

Python

Python SDKは、PyPIでclaude-code-sdkとして利用できます:

pip install claude-code-sdk

前提条件:

  • Python 3.10以上
  • Node.js
  • Claude Code CLI: npm install -g @anthropic-ai/claude-code

基本的な使用方法:

import anyio
from claude_code_sdk import query, ClaudeCodeOptions, Message

async def main():
    messages: list[Message] = []
    
    async for message in query(
        prompt="foo.pyについての俳句を書いてください",
        options=ClaudeCodeOptions(max_turns=3)
    ):
        messages.append(message)
    
    print(messages)

anyio.run(main)

Python SDKは、ClaudeCodeOptionsクラスを通じてコマンドラインSDKでサポートされているすべての引数を受け付けます:

from claude_code_sdk import query, ClaudeCodeOptions
from pathlib import Path

options = ClaudeCodeOptions(
    max_turns=3,
    system_prompt="あなたは役立つアシスタントです",
    cwd=Path("/path/to/project"),  # 文字列またはPathを指定可能
    allowed_tools=["Read", "Write", "Bash"],
    permission_mode="acceptEdits"
)

async for message in query(prompt="こんにちは", options=options):
    print(message)

高度な使用方法

以下のドキュメントではコマンドラインSDKを例として使用していますが、TypeScriptやPython SDKでも同様に使用できます。

マルチターン会話

マルチターン会話では、会話を再開したり、最新のセッションから続行したりできます:

# 最新の会話を続行
$ claude --continue

# 続行して新しいプロンプトを提供
$ claude --continue "より良いパフォーマンスのためにこれをリファクタリングしてください"

# セッションIDで特定の会話を再開
$ claude --resume 550e8400-e29b-41d4-a716-446655440000

# プリントモード(非インタラクティブ)で再開
$ claude -p --resume 550e8400-e29b-41d4-a716-446655440000 "テストを更新してください"

# プリントモード(非インタラクティブ)で続行
$ claude -p --continue "エラー処理を追加してください"

カスタムシステムプロンプト

Claudeの動作を導くためのカスタムシステムプロンプトを提供できます:

# システムプロンプトをオーバーライド(--printでのみ機能)
$ claude -p "REST APIを構築してください" --system-prompt "あなたはシニアバックエンドエンジニアです。セキュリティ、パフォーマンス、保守性に焦点を当ててください。"

# 特定の要件を持つシステムプロンプト
$ claude -p "データベーススキーマを作成してください" --system-prompt "あなたはデータベースアーキテクトです。PostgreSQLのベストプラクティスを使用し、適切なインデックスを含めてください。"

デフォルトのシステムプロンプトに指示を追加することもできます:

# システムプロンプトを追加(--printでのみ機能)
$ claude -p "REST APIを構築してください" --append-system-prompt "コードを書いた後、必ず自分でコードレビューを行ってください。"

MCP設定

モデルコンテキストプロトコル(MCP)を使用すると、外部サーバーから追加のツールやリソースでClaude Codeを拡張できます。--mcp-configフラグを使用して、データベースアクセス、API統合、カスタムツールなどの特殊な機能を提供するMCPサーバーを読み込むことができます。

MCPサーバーを含むJSON設定ファイルを作成します:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/files"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

そしてClaude Codeで使用します:

# 設定からMCPサーバーを読み込む
$ claude -p "プロジェクト内のすべてのファイルをリストアップしてください" --mcp-config mcp-servers.json

# 重要:MCPツールは--allowedToolsを使用して明示的に許可する必要があります
# MCPツールは次の形式に従います:mcp__$serverName__$toolName
$ claude -p "TODOコメントを検索してください" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__filesystem__read_file,mcp__filesystem__list_directory"

# 非インタラクティブモードで権限プロンプトを処理するためのMCPツールを使用
$ claude -p "アプリケーションをデプロイしてください" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__permissions__approve" \
  --permission-prompt-tool mcp__permissions__approve

MCPツールを使用する場合、--allowedToolsフラグを使用して明示的に許可する必要があります。MCPツール名はmcp__<serverName>__<toolName>のパターンに従います:

  • serverNameはMCP設定ファイルのキーです
  • toolNameはそのサーバーが提供する特定のツールです

このセキュリティ対策により、MCPツールは明示的に許可された場合にのみ使用されます。

サーバー名のみを指定した場合(つまり、mcp__<serverName>)、そのサーバーからのすべてのツールが許可されます。

グロブパターン(例:mcp__go*)はサポートされていません。

カスタム権限プロンプトツール

オプションで、--permission-prompt-toolを使用して、ユーザーがモデルに特定のツールを呼び出す権限を付与するかどうかを確認するために使用するMCPツールを渡すことができます。モデルがツールを呼び出すと、次のことが起こります:

  1. まず権限設定をチェックします:すべてのsettings.jsonファイル、およびSDKに渡された--allowedTools--disallowedTools。これらのいずれかがツール呼び出しを許可または拒否する場合、ツール呼び出しを続行します
  2. それ以外の場合は、--permission-prompt-toolで提供したMCPツールを呼び出します

--permission-prompt-tool MCPツールにはツール名と入力が渡され、結果を含むJSON文字列化されたペイロードを返す必要があります。ペイロードは次のいずれかである必要があります:

// ツール呼び出しが許可される
{
  "behavior": "allow",
  "updatedInput": {...}, // 更新された入力、または元の入力をそのまま返す
}

// ツール呼び出しが拒否される
{
  "behavior": "deny",
  "message": "..." // 権限が拒否された理由を説明する人間が読める文字列
}

例えば、TypeScript MCP権限プロンプトツールの実装は次のようになります:

const server = new McpServer({
  name: "Test permission prompt MCP Server",
  version: "0.0.1",
});

server.tool(
  "approval_prompt",
  '権限チェックをシミュレート - 入力に"allow"が含まれている場合は承認、それ以外は拒否',
  {
    tool_name: z.string().describe("権限を要求しているツール"),
    input: z.object({}).passthrough().describe("ツールの入力"),
  },
  async ({ tool_name, input }) => {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            JSON.stringify(input).includes("allow")
              ? {
                  behavior: "allow",
                  updatedInput: input,
                }
              : {
                  behavior: "deny",
                  message: "テストapproval_promptツールによって権限が拒否されました",
                }
          ),
        },
      ],
    };
  }
);

このツールを使用するには、MCPサーバーを追加し(例:--mcp-configで)、次のようにSDKを呼び出します:

claude -p "..." \
  --permission-prompt-tool mcp__test-server__approval_prompt \
  --mcp-config my-config.json

使用上の注意:

  • updatedInputを使用して、権限プロンプトが入力を変更したことをモデルに伝えます。それ以外の場合は、上記の例のように、updatedInputを元の入力に設定します。例えば、ツールがファイル編集の差分をユーザーに表示し、手動で差分を編集できるようにする場合、権限プロンプトツールはその更新された編集を返す必要があります。
  • ペイロードはJSON文字列化する必要があります

利用可能なCLIオプション

SDKはClaude Codeで利用可能なすべてのCLIオプションを活用します。SDK使用のための主要なオプションは次のとおりです:

フラグ説明
--print, -p非インタラクティブモードで実行claude -p "クエリ"
--output-format出力形式を指定(text, json, stream-jsonclaude -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-configJSONファイルからMCPサーバーを読み込むclaude --mcp-config servers.json
--permission-prompt-tool権限プロンプトを処理するMCPツール(--printでのみ)claude --permission-prompt-tool mcp__auth__prompt

CLIオプションと機能の完全なリストについては、CLI使用方法とコントロールのドキュメントを参照してください。

出力形式

SDKは複数の出力形式をサポートしています:

テキスト出力(デフォルト)

応答テキストのみを返します:

$ claude -p "src/components/Header.tsxファイルを説明してください"
# 出力: これはReactコンポーネントで...を表示しています

JSON出力

メタデータを含む構造化データを返します:

$ claude -p "データレイヤーはどのように機能しますか?" --output-format json

応答形式:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "ここに応答テキスト...",
  "session_id": "abc123"
}

ストリーミングJSON出力

受信したメッセージごとにストリーミングします:

$ claude -p "アプリケーションを構築してください" --output-format stream-json

各会話は最初のinitシステムメッセージで始まり、ユーザーとアシスタントのメッセージのリストが続き、最後に統計情報を含むresultシステムメッセージで終わります。各メッセージは別々のJSONオブジェクトとして出力されます。

メッセージスキーマ

JSON APIから返されるメッセージは、次のスキーマに従って厳密に型付けされています:

type SDKMessage =
  // アシスタントメッセージ
  | {
      type: "assistant";
      message: Message; // Anthropic SDKから
      session_id: string;
    }

  // ユーザーメッセージ
  | {
      type: "user";
      message: MessageParam; // Anthropic SDKから
      session_id: string;
    }

  // 最後のメッセージとして出力される
  | {
      type: "result";
      subtype: "success";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      result: string;
      session_id: string;
      total_cost_usd: float;
    }

  // 最大ターン数に達した場合、最後のメッセージとして出力される
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      session_id: string;
      total_cost_usd: float;
    }

  // 会話の開始時に最初のメッセージとして出力される
  | {
      type: "system";
      subtype: "init";
      apiKeySource: string;
      cwd: string;
      session_id: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
    };

これらの型はまもなくJSONSchema互換形式で公開される予定です。メインのClaude Codeパッケージではセマンティックバージョニングを使用して、この形式の破壊的変更を伝えています。

MessageMessageParamの型はAnthropic SDKで利用できます。例えば、AnthropicのTypeScriptPythonのSDKを参照してください。

シンプルなスクリプト統合

#!/bin/bash

# Claudeを実行して終了コードをチェックするシンプルな関数
run_claude() {
    local prompt="$1"
    local output_format="${2:-text}"

    if claude -p "$prompt" --output-format "$output_format"; then
        echo "成功!"
    else
        echo "エラー: Claudeが終了コード$?で失敗しました" >&2
        return 1
    fi
}

# 使用例
run_claude "CSVファイルを読み込むPython関数を書いてください"
run_claude "このデータベースクエリを最適化してください" "json"

Claudeでファイルを処理する

# ファイルをClaude経由で処理
$ cat mycode.py | claude -p "このコードのバグをレビューしてください"

# 複数のファイルを処理
$ for file in *.js; do
    echo "$fileを処理中..."
    claude -p "このファイルにJSDocコメントを追加してください:" < "$file" > "${file}.documented"
done

# パイプラインでClaudeを使用
$ grep -l "TODO" *.py | while read file; do
    claude -p "このファイル内のすべてのTODO項目を修正してください" < "$file"
done

セッション管理

# セッションを開始してセッションIDをキャプチャ
$ claude -p "新しいプロジェクトを初期化してください" --output-format json | jq -r '.session_id' > session.txt

# 同じセッションを続行
$ claude -p --resume "$(cat session.txt)" "ユニットテストを追加してください"

ベストプラクティス

  1. JSON出力形式を使用するとプログラムによる応答の解析が容易になります:

    # jqでJSON応答を解析
    result=$(claude -p "コードを生成してください" --output-format json)
    code=$(echo "$result" | jq -r '.result')
    cost=$(echo "$result" | jq -r '.cost_usd')
    
  2. エラーを適切に処理する - 終了コードとstderrをチェックします:

    if ! claude -p "$prompt" 2>error.log; then
        echo "エラーが発生しました:" >&2
        cat error.log >&2
        exit 1
    fi
    
  3. セッション管理を使用するとマルチターン会話でコンテキストを維持できます

  4. 長時間実行される操作にはタイムアウトを検討する

    timeout 300 claude -p "$complex_prompt" || echo "5分後にタイムアウトしました"
    
  5. 複数のリクエストを行う際にはレート制限を尊重するため、呼び出し間に遅延を追加します

実際のアプリケーション

Claude Code SDKを使用すると、開発ワークフローとの強力な統合が可能になります。注目すべき例として、Claude Code GitHub Actionsがあります。これはSDKを使用して、GitHubワークフローで直接自動コードレビュー、PR作成、イシュートリアージ機能を提供します。

関連リソース