Claude Media
MAX_MCP_OUTPUT_TOKENSとは — MCPツール出力の上限を変える環境変数
Claude CodeMCPTips

MAX_MCP_OUTPUT_TOKENSとは — MCPツール出力の上限を変える環境変数

MAX_MCP_OUTPUT_TOKENSは、MCPツールが返す結果の最大トークン数を決める環境変数です。既定値・警告との違い・サーバー側の個別上限との使い分けをまとめます。

読了目安 約9分

MAX_MCP_OUTPUT_TOKENSは、MCP(Model Context Protocol)ツールが1回の呼び出しで返せる出力の最大トークン数を決める環境変数です。既定値は25,000トークンで、10,000トークンを超えると警告が出ます。データベースやファイルシステム系のMCPサーバーは応答が数万トークンに達することがあります。

分析用途のサーバーはこの傾向が特に強く、ClickHouse・DuckDB・BigQueryのMCP比較で読み取り専用の既定値と合わせて扱っています。ここでは、この変数が何を変え、何を変えないのかを、症状の側から切り分けます。

警告が出たとき、実際に起きていること

警告が出る10,000トークンと、結果が会話に入らなくなる25,000トークンは別の線です。変数で動かせるのは後者だけで、警告のしきい値は固定です。

手順

MCPツールの結果が大きいときの流れ

  1. 1

    10,000トークンを超える

    警告が表示されます。結果は上限以下なので、保存への切り替えは起きません。

  2. 2

    上限(既定25,000トークン)を超える

    画像を含まない結果は、会話に流し込まれずファイルへ保存されます。会話にはそのファイルのパスを知らせるメッセージが入り、Claudeは中身が必要になったときにファイルを読みます。

  3. 3

    上限を上げる

    下のように指定してclaudeを起動します。2の切り替わりが起きる線だけが動きます。

export MAX_MCP_OUTPUT_TOKENS=50000
claude

保存先は、そのセッションのtool-resultsディレクトリで、~/.claude/projects/の下にあります。ツール呼び出しは失敗しません。ただし「結果が会話に載っていない」状態にはなるため、出力の一部しか見えていないように感じることがあります。

保存された結果は残り続けません。cleanupPeriodDays(既定30日)を過ぎたファイルは、保持期間を安全に判定できるかぎり自動で削除されます。判定できないときは削除が止まり、設定ファイルの読み取りエラーなどが原因なら/statusに警告が出ます。

画像だけは、サーバー側の宣言でも逃げられない

変数の対象範囲は、ツールがanthropic/maxResultSizeCharsを宣言しているかどうかで変わります。この2つは、テキストと画像で扱いが分かれます。

くらべる

宣言ありのツールが返す2種類の結果

宣言側が優先

テキスト

anthropic/maxResultSizeCharsで宣言した文字数上限が使われます。MAX_MCP_OUTPUT_TOKENSをいくつにしても関係しません。

変数が効く

画像

宣言があっても、変数のトークン上限の対象です。画像で上限にかかるなら、変数を上げる以外に手段がありません。

画像については、v2.1.283で「MCPツールが返した画像は元のバイト列もファイルに保存され、BashやReadから開ける」ように改善されています。会話に入る側のコピーは、モデルの画像サイズ制限に収まるよう縮小・圧縮されることがあります。対象の形式はPNG・JPEG・GIF・WebPで、Claudeは保存された原本を切り抜いたり形式変換したりして使えます。保存先は、テキスト結果と同じtool-resultsディレクトリです。

サーバーを自分で直せるかで、取れる手段が変わる

MCPサーバーを自作・カスタマイズできるかどうかで、選択肢は2つに分かれます。

立場手段効果
MCPサーバーの利用者(設定変更のみ)手段MAX_MCP_OUTPUT_TOKENS を上げる効果宣言のないツール全部の上限が一律で上がる
MCPサーバーの実装者手段tools/list の _meta に anthropic/maxResultSizeChars を宣言効果そのツールのテキスト結果だけ、最大500,000文字まで個別に引き上げ

実装者は、ツール定義に次のように書きます。データベースのスキーマ全体やファイルツリーのように、大きいが必要な出力を返すツールが対象です。

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

宣言済みのツールなら、利用者はMAX_MCP_OUTPUT_TOKENSを触らなくても大きなテキスト結果を受け取れます。接続や認証を含むMCPサーバー追加の手順全体は、Claude Code MCP設定ガイドにまとめています。

この宣言は後から加わった仕組みで、v2.1.91で導入されました。v2.1.98では「宣言してもトークン基準の保存処理を回避できないツールがある」不具合が修正されています。古いClaude Codeでは宣言が効かない可能性があるため、まずバージョンを確かめます。

v2.1.287では、上限を大きく超えるMCPツール結果の扱いも改善され、メモリ使用量とセッションファイルが小さくなりました。上限を大きく超える結果について、トークン数を数えるための追加アップロードも不要になっています。

値を変えても警告や切り詰めが消えないとき

上げたはずなのに症状が続くときは、次の順に疑います。

  • 対象のツールがanthropic/maxResultSizeCharsを宣言していないか: 宣言済みのツールは、テキスト出力についてこの変数を無視します。宣言はツール定義(tools/listの_meta)に書かれるもので、Claude Codeの設定側では変えられません
  • 画像を返していないか: 画像は宣言があっても変数の上限にかかります
  • 起動済みのセッションにexportしていないか: 値を変えたら、claudeを起動し直します
  • settings.jsonのenvブロックに別の値がないか: envブロックの値は、シェルでexportした同名の変数を上書きします。複数の設定ファイルが同じ変数を持つなら、優先度の高い方が使われます
  • 警告そのものを消したいのではないか: 警告のしきい値は変数で動かせないので、出力そのものを減らす方向で対応します
  • Claude Codeが古くないか: v2.1.128では、サーバーが構造化コンテンツとコンテンツブロックの両方を返すと画像が落ちる不具合が、v2.1.136では、コンテンツブロックを返すと結果が見えなくなる不具合が修正されています。どちらも上限とは無関係の旧版の問題なので、症状が似ていれば更新を先に試します

envブロックが効かないセッションもあります。Claude Desktopアプリやセルフホスト環境のランナーがセッションを起動した場合は、起動側が組み立てた環境が優先されます。起動環境がすでに設定している変数は、どの設定ファイルのenv値も無視されます。無視された変数の名前はデバッグログに出ます。

プロジェクトやローカルの設定にあるenvは、ワークスペースを信頼したあとに適用されます。-pモードでは信頼ダイアログが出ないため、起動時に適用されます。モデル選択・タイムアウト・上限・機能の切り替えなど、安全と分類された変数は、起動時にすべての設定ファイルから適用されます。v2.1.246以降では、/cdで作業ディレクトリを移すと、移動先のプロジェクト・ローカルのenv値が前のディレクトリの値の上に重なります。

シェル側の値はenv | grep MAX_MCP_OUTPUT_TOKENS(PowerShellならGet-ChildItem Env:MAX_MCP_OUTPUT_TOKENS)で確認できます。/statusのSetting sources行で、どの設定ファイルが読み込まれたかも分かります。

設定ファイル同士では、優先度が高い順にマネージド設定、コマンドライン、プロジェクトのローカル設定、共有のプロジェクト設定、ユーザー設定です。envブロックはこの順で解決される普通のキーとして扱われます。書き方の全般は、Claude Code環境変数リファレンスにまとめています。

上限を上げる前に考えること

上限を上げると、警告や保存への切り替わりは減ります。代わりに、大きな結果がそのまま会話のコンテキストウィンドウを占めます。

  • 特定のMCPサーバーで頻繁に警告が出るなら、サーバー開発元にanthropic/maxResultSizeCharsの宣言かページネーションを相談する方が、根本解決に近づきます
  • 開発元に頼めない外部サーバーで、大きな結果自体が必要なときは、変数を上げる手があります
  • そもそも出力が小さく済むサーバーを選び直す手もあります。用途別の選び方はおすすめMCPサーバー10選にあります

出力が大きくなりやすいのは、クエリー結果をそのまま返すツール、ファイルツリーやリポジトリ全体を列挙するツール、ログやモニタリングデータを集計せず返すツールです。単一のレコードを取るAPI呼び出しや、要約済みの結果を返すツールは、この上限にかかりにくい傾向があります。

なお、Claude Codeでこの変数が働くのはMCPツールの応答だけです。モデルへの接続先を決める設定とは別物です。

似た名前の環境変数と混同しない

Claude Codeには「出力の上限」を扱う変数が複数あり、対象が違います。

環境変数上限をかける対象既定値
MAX_MCP_OUTPUT_TOKENS上限をかける対象MCPツールの応答既定値25,000トークン
CLAUDE_CODE_MAX_OUTPUT_TOKENS上限をかける対象Claudeモデル自体の出力(ほとんどのリクエスト)既定値モデルにより変動(未知のモデルIDは32,000、上限128,000)
BASH_MAX_OUTPUT_LENGTH上限をかける対象bashコマンドの出力を読み戻す文字数(設定bashOutputMaxCharsがあればこの変数は無視される)既定値30,000文字(最大150,000)

MCPサーバーの応答が切り詰められて困っているときにCLAUDE_CODE_MAX_OUTPUT_TOKENSを上げても効果はありません。逆にモデルの生成が途中で止まる問題は、MAX_MCP_OUTPUT_TOKENSでは直りません。なおCLAUDE_CODE_MAX_OUTPUT_TOKENSを上げると、自動コンパクションまでに使える有効なコンテキストが減ります。値がモデルの上限を超えていれば、上限まで下げて扱われます。

同じ「exceeds maximum allowed tokens」という文言でも、Readツールがファイル1回分の読み込みで返す量にかける上限は別物です。見分け方は「File content exceeds maximum allowed tokens」エラーの原因と対処法にあります。MCPツールの説明文が2,048文字で切り詰められる仕組みは、別の環境変数CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTHが担っています。この変数は各サーバーのinstructionsにも効き、v2.1.280以降が必要です。説明文の文字数上限を変える方法を参照してください。

どれも「1回の応答をどこまで許すか」の上限です。MCPサーバーを増やすほど毎ターン積み上がる基礎コストは減らせません。ツール定義の読み込みで生じる恒常的な消費は、MCPのトークンオーバーヘッドを抑える設定で扱っています。

よくある質問

保存されたファイルはいつまで残りますか

~/.claude/projects/の下のtool-resultsディレクトリに置かれ、cleanupPeriodDaysで決まる期間(既定30日、最小1日。0は指定できません)を過ぎると、保持期間を判定できるかぎり自動で削除されます。--no-session-persistenceか環境変数CLAUDE_CODE_SKIP_PROMPT_HISTORYでセッションの保存を無効にした場合は、画像のファイルが書かれません。Claudeには会話内のコピーだけが渡ります。

上限を極端に大きくしても問題ありませんか

サーバー側の宣言による個別上限は、500,000文字が天井です。MAX_MCP_OUTPUT_TOKENSの説明には、このような上限値は書かれていません。大きくするほど、1回の応答がコンテキストウィンドウを占める割合は増えます。

CLAUDE_CODE_MAX_OUTPUT_TOKENSと同時に設定できますか

できます。片方はMCPツールの応答、もう片方はモデル自体の出力を制御するので、干渉しません。

まとめ

変数で動くのは保存への切り替え線だけなので、警告そのものは出力を減らして避けます。大きな結果が必要で、開発元にも頼めないサーバーに限って、変数を上げる手が残ります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →