メインコンテンツへスキップ
claude-code routines mcp github automation

Claude Code Routines × GitHub連携のハマりポイント

Claude Code Routines × GitHub連携のハマりポイントのアイキャッチ画像
目次

TL;DR

はじめに

本記事の内容は2026年4月時点の情報です。Claude Code Routinesはリサーチプレビュー段階のため、今後のアップデートで仕様が変更される可能性があります。

2026年4月にリサーチプレビューとして公開された Claude Code Routines は、定期実行・API呼び出し・GitHubイベントをトリガーとして、Claude.ai上でプロンプトを自動実行する機能です（Pro / Max / Team / Enterpriseプランで利用可能）。

Routine作成画面。トリガー（スケジュール/GitHubイベント/API）やコネクタを設定できる

GitHubリポジトリとの連携は、Claude.aiアカウントレベルのGitHub連携（GitHub Appまたは /web-setup による gh トークン同期）で行います。Routine作成画面の「コネクタ」セクションにはSlackやLinearなどの外部サービスが並びますが、GitHubはここには含まれません。GitHub連携済みの状態でRoutineにリポジトリを追加すると、Routine内からリポジトリへのファイル操作が可能になります。

RoutineがGitHubリポジトリにファイルをコミットする際、筆者の環境ではMCPツール（mcp__github__create_or_update_file）が使われていました。「毎日の処理結果を自動でGitHubにコミットする」という使い方は自然な発想ですが、実際に運用してみると、このMCPツール呼び出しで想定外の制限に遭遇しました。この記事では、実際にハマった問題と回避策を共有します。

課題1: MCPタイムアウト — 大きなファイルが保存できない

症状

Routineで生成したレポート（約30KBのMarkdownファイル）を mcp__github__create_or_update_file で保存しようとしたところ、以下のエラーが発生しました。

API Error: Stream idle timeout - partial response received

何度リトライしても同じ結果です。ファイルの中身を短くすると成功するため、ファイルサイズに起因する問題であることはすぐに分かりました。

原因調査: GitHub API側の制限？

最初に疑ったのはGitHub REST APIのファイルサイズ制限です。しかし、GitHub Contents APIの制限は 100MB であり、約30KBのテキストが引っかかるはずがありません。

GitHub Contents API: ファイルサイズ上限 100MB
実際のファイル: 約30KB
→ API側の制限ではない

原因調査: Claude.aiプラットフォーム側のタイムアウト？

次に、Claude.ai側のMCPツール呼び出しにタイムアウトがあるのではないかと疑いました。

Claude Code CLIには MCP_TIMEOUT という環境変数がありますが、これは主にMCPサーバーの起動時のタイムアウトに関わるもので、個別のツール呼び出しのタイムアウトを直接制御できるかは明確ではありません。いずれにせよ、Routinesのクラウド実行環境ではユーザーがこの値を設定する手段は提供されていません。

調査結果

エラーメッセージ（Stream idle timeout）とファイルサイズの相関から、最も可能性が高いのは MCPツール呼び出し時のタイムアウト です。

実験的に確認した境界値の目安です（筆者の環境での実測値）。

ファイルサイズ結果
~5,000バイト安定して成功
~8,500バイト安定して成功
~11,500バイト成功（上限付近）
~15,000バイト以上タイムアウト

注意: この境界値はネットワーク状況やサーバー負荷によって変動する可能性があります。安全マージンを取って 1ファイルあたり10,000バイト以下 を目安にするのが実用的でした。

Bash経由の git push は使えるか？

MCPツールを介さずにファイルを保存できないかも調べました。Routineにはコード実行機能があるため、Bash経由で git push するアプローチも考えられます。

しかし、サンドボックス環境を確認したところ、GITHUB_TOKEN や GH_TOKEN 環境変数、gh CLI、SSHキー、~/.netrc のいずれも存在せず、Bash経由でのGitHub認証手段はありませんでした。

これはセキュリティ上妥当な設計です。Anthropicの公式ドキュメントでも、サンドボックス内にはgit認証情報や署名鍵は配置せず、GitHub操作はセキュアプロキシを通じてスコープ付きクレデンシャルで処理すると明記されています。LLMに直接git pushの認証情報を渡さないことで、意図しないリポジトリ操作のリスクを抑えています。

Routineサンドボックスの認証構造。Bash経由のgit pushは認証情報がなくブロックされ、MCP経由のみGitHubにアクセスできる

つまり、タイムアウト問題のフォールバックとしてBash経由のgit pushは使えず、MCPの枠内で解決する必要があります。

回避策

タイムアウト回避: ファイル分割保存

MCPのタイムアウト制限を回避するために筆者が採用したのは、コンテンツを10,000バイト以下のチャンクに分割して保存 する方法です。

プロンプトでの分割指示

Routineのプロンプトに以下のような分割ルールを明記します。

### ファイルサイズ制限と保存手順

MCPタイムアウト制限により、1回の `create_or_update_file` で保存できる
コンテンツは **約10,000バイトが上限** です。

出力が10,000バイトを超える場合:
1. コンテンツをセクション単位で分割する（各パート10,000バイト以下）
2. `create_or_update_file` で Part 1 を保存する
3. 成功を確認してから Part 2 を保存する（並列実行禁止）
4. 全パート保存後、Part 1 の末尾に各パートへのリンクを追記する

タイムアウトが発生した場合:
→ さらに細かく分割して再試行する（1パート8,000バイト以下）

ポイントは「並列実行禁止」を明記することです。LLMは効率化のために複数のツール呼び出しを並列実行しようとすることがありますが、この場合は逆効果になります。

また、分割したパート間のナビゲーションのために、Part 1の末尾に後続パートへのリンクを追記しておくとGitHub上での閲覧性が上がります。Part 1を更新する際は、作成時のレスポンスから取得したSHAを指定して create_or_update_file を再度呼び出します。

分割保存のデメリット

この方式には明確なトレードオフがあります。

それでもこの方式を採用した理由は、現状では他に実用的な選択肢が見当たらなかったからです。前述の通りBash経由のgit pushはサンドボックスのセキュリティ設計上使えず、タイムアウト設定の変更もできないため、消去法でファイル分割が最も確実な回避策になりました。

補足: タイムゾーンのずれに注意

クラウド実行環境がUTCで動くこと自体は予想の範囲ですが、Routineのスケジュール設定がJSTで指定できるため、つい内部の日時判定もJSTだろうと思い込みがちです。

実際には、LLMが「今日の日付」を判定する際にUTC基準になるケースがありました。例えばJST 4/25 07:00に実行すると、UTC上は4/24 22:00なので、日付ベースのファイル名やコミットメッセージが前日の日付になります。

プロンプトの冒頭にタイムゾーン指示を明記しておくと、この問題を防げます。

**⚠️ タイムゾーン: 全ての日時判定はJST（UTC+9）で行うこと。**
日付・曜日・ファイル名・コミットメッセージの日付は全てJST基準。
実行環境がUTCの場合は+9時間して判定する。

まとめ

Claude Code RoutinesからGitHub MCPを使う際の主な制限と回避策をまとめます。

問題原因回避策
大きなファイルの保存失敗MCPツール呼び出しのタイムアウト10,000バイト以下に分割保存
Bash経由のgit pushが使えないサンドボックスのセキュリティ設計MCPの枠内で対処
日付・曜日がずれる実行環境がUTCプロンプトでJST指定を明記

これらの制限は、Claude Code Routinesがまだリサーチプレビュー段階であることを考えると、今後改善される余地があります。特にMCPタイムアウトの設定可能化については、ユーザーからのフィードバックが集まれば対応されるかもしれません。

現時点では「制限を理解した上で、プロンプト設計で回避する」のが最も実用的なアプローチだと感じています。この記事が、同じ壁にぶつかった方の参考になれば幸いです。

参考

ZSL
ZSL

AIエンジニア

生成AIを活用した開発ワークフローの研究・実践をしています。