Claude Code SDK

Claude Code SDKは、Claude CodeをサブプロセスとしてRunning可能にし、Claudeの機能を活用したAI駆動のコーディングアシスタントやツールを構築する方法を提供します。

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

認証

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

Anthropic ConsoleでAnthropic APIキーを作成します
次に、ANTHROPIC_API_KEY環境変数を設定します。このキーを安全に保存することをお勧めします（例：Github secretを使用）

基本的なSDKの使用方法

Claude Code SDKを使用すると、アプリケーションから非対話モードでClaude Codeを使用できます。

コマンドライン

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

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

# パイプを使用してstdinを提供
$ 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`	実行可能ファイルに渡す引数	`[]`
`pathToClaudeCodeExecutable`	Claude 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設定

Model Context Protocol（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>）、そのサーバーのすべてのツールが許可されます。

Globパターン（例：mcp__go*）はサポートされていません。

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

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

まず権限設定をチェックします：すべてのsettings.jsonファイル、およびSDKに渡された--allowedToolsと--disallowedTools；これらのいずれかがツール呼び出しを許可または拒否する場合、ツール呼び出しを続行します
そうでなければ、--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-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は複数の出力形式をサポートしています：

テキスト出力（デフォルト）

レスポンステキストのみを返します：

$ 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パッケージにセマンティックバージョニングを使用しています。

MessageとMessageParam型は、Anthropic SDKで利用できます。例えば、Anthropic TypeScriptおよびPython SDKを参照してください。

入力形式

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

テキスト入力（デフォルト）

入力テキストは引数として提供できます：

$ claude -p "このコードを説明してください"

または、入力テキストはstdin経由でパイプできます：

$ echo "このコードを説明してください" | claude -p

ストリーミングJSON入力

各メッセージがユーザーターンを表すstdin経由で提供されるメッセージのストリーム。これにより、claudeバイナリを再起動することなく会話の複数ターンが可能になり、リクエストを処理している間にモデルにガイダンスを提供できます。

各メッセージは、出力メッセージスキーマと同じ形式に従う JSON ‘User message’オブジェクトです。メッセージはjsonl形式を使用してフォーマットされ、入力の各行が完全なJSONオブジェクトです。ストリーミングJSON入力には-pと--output-format stream-jsonが必要です。

現在、これはテキストのみのユーザーメッセージに制限されています。

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"このコードを説明してください"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

例

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

#!/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)" "単体テストを追加してください"

ベストプラクティス

プログラム的なレスポンス解析にはJSON出力形式を使用：

# jqでJSONレスポンスを解析
result=$(claude -p "コードを生成してください" --output-format json)
code=$(echo "$result" | jq -r '.result')
cost=$(echo "$result" | jq -r '.cost_usd')

エラーを適切に処理 - 終了コードとstderrをチェック：

if ! claude -p "$prompt" 2>error.log; then
    echo "エラーが発生しました：" >&2
    cat error.log >&2
    exit 1
fi

マルチターン会話でコンテキストを維持するためにセッション管理を使用

長時間実行される操作にはタイムアウトを考慮：

timeout 300 claude -p "$complex_prompt" || echo "5分後にタイムアウトしました"

複数のリクエストを行う際は、呼び出し間に遅延を追加してレート制限を尊重

実世界のアプリケーション

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

はじめに

Claudeで構築

デプロイメント

管理

リファレンス

リソース

認証

基本的なSDKの使用方法

コマンドライン

TypeScript

Python

高度な使用方法

マルチターン会話

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

MCP設定

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

利用可能なCLIオプション

出力形式

テキスト出力（デフォルト）

JSON出力

ストリーミングJSON出力

メッセージスキーマ

入力形式

テキスト入力（デフォルト）

ストリーミングJSON入力

例

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

Claudeでファイルを処理

セッション管理

ベストプラクティス

実世界のアプリケーション

関連リソース

はじめに

Claudeで構築

デプロイメント

管理

リファレンス

リソース

​認証

​基本的なSDKの使用方法

​コマンドライン

​TypeScript

​Python

​高度な使用方法

​マルチターン会話

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

​MCP設定

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

​利用可能なCLIオプション

​出力形式

​テキスト出力（デフォルト）

​JSON出力

​ストリーミングJSON出力

​メッセージスキーマ

​入力形式

​テキスト入力（デフォルト）

​ストリーミングJSON入力

​例

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

​Claudeでファイルを処理

​セッション管理

​ベストプラクティス

​実世界のアプリケーション

​関連リソース

認証

基本的なSDKの使用方法

コマンドライン

TypeScript

Python

高度な使用方法

マルチターン会話

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

MCP設定

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

利用可能なCLIオプション

出力形式

テキスト出力（デフォルト）

JSON出力

ストリーミングJSON出力

メッセージスキーマ

入力形式

テキスト入力（デフォルト）

ストリーミングJSON入力

例

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

Claudeでファイルを処理

セッション管理

ベストプラクティス

実世界のアプリケーション

関連リソース