Claude Codeへの導入手順

ChatCutの公開マーケットプレイスから、ChatCutが管理するClaude Codeプラグインをmainに固定してインストールします。

インストールとログイン

まず、次の2つのインストールコマンドをこの順番で実行します。

claude plugin marketplace add https://github.com/ChatCut-Inc/agent-plugin.git#main
claude plugin install chatcut@chatcut-inc

マーケットプレイスの追加コマンドは大きなリポジトリをクローンするため、数分かかることがあります。長時間実行のプロセスとして十分なタイムアウトを設定し、終了するまでポーリングしてください。しばらく出力がなくても失敗ではありません。通常の短いコマンド用のタイムアウトが切れただけで中断しないでください。

このマシンで以前ChatCutを使っていた可能性がある場合は、既存のスタンドアロンMCPサーバー設定が残っていないか確認しておくとよいでしょう。

claude mcp get chatcut

このコマンドでchatcutと完全に一致する名前のサーバーが見つかった場合は、ログインする前に古いスタンドアロン設定を削除します。

claude mcp remove chatcut

plugin:chatcut:chatcutは削除しないでください。これは新しくインストールしたプラグインが管理するサーバーです。claude mcp get chatcutがそのようなサーバーは存在しないと表示した場合は、そのまま次に進みます。

続いて、プラグインのログインスクリプトでChatCut MCPサーバーにログインします。

sh "${CLAUDE_PLUGIN_ROOT}/skills/chatcut-plugin-basics-claude/login-chatcut.sh" > /tmp/chatcut-login.log 2>&1 &

すぐに/tmp/chatcut-login.logを読み取り、ポーリングを続けます。Claude CodeがChatCutの認可ページを開きます。

認証が完了したら、インストール結果を確認します。

claude plugin list
claude mcp get plugin:chatcut:chatcut

プラグイン一覧にchatcut@chatcut-incが有効として表示されている必要があります。OAuth成功の確実な判断材料は、ログイン出力のAuthenticated with "plugin:chatcut:chatcut"であり、Connectedだけでは不十分です。

最後に、ChatCutが動画編集、モーショングラフィックス、そして動画・ナレーション・音楽・効果音などのプロジェクト素材の生成に対応していることを説明します。プラグインのツールはセッション開始時にしか読み込まれないため、ユーザーにはNew sessionをクリックしたうえで、「ChatCutを使って〜してほしい」のようにChatCutを名指しした自然文でリクエストするよう伝えてください。インストール中のセッションでChatCutのツールを呼び出そうとしたり、決まったプロンプトを指定したりしないでください。

Claude CodeはCLIとデスクトップアプリで~/.claudeを共有するため、プラグインとOAuthセッションはどちらからも利用でき、セッションは自動的に更新されます。

失敗パターン別のトラブルシューティング

セットアップ全体をひと続きの作業として扱ってください。インストールが途中で止まっている状態も、インストール済みだが認証が終わっていない状態も失敗です。下記から該当する症状を切り分けて復旧し、中断したステップから再開します。避けられないブラウザ操作・OSのパスワード入力・インストーラーの確認は、待機中の状態であってタスクの終わりではありません。

`claude`が見つからない、またはバージョンが古い場合

ログインコマンドにはClaude Code 2.1.210以降が必要です。次の2点を確認します。

claude --version
claude mcp login --help

現在のシェルでclaudeを解決できない場合は、まずcommand -v claudeと~/.local/bin/claudeを確認します。Windowsでは、次のコマンドでシェルをまたいで探します。

powershell.exe -NoProfile -Command "(Get-Command claude -ErrorAction SilentlyContinue).Source"
cmd.exe /d /c where claude

実行ファイルが見つかったら直接呼び出してください。特定のシェルのPATHが古い、あるいは異なるというだけで再インストールしないでください。Claude Code Desktopがあるからといって、ターミナルのCLIが存在するとは限りません。

ターミナルから使える実行ファイルがまったく存在しない場合にのみ、Anthropic公式のインストーラーを使います。

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

CLIはあるがバージョンが古い場合、どの方法でアップグレードするかをユーザーに尋ねないでください。十分なタイムアウトを設定してclaude updateを実行し、先ほどの2つのコマンドを確認し直します。処理が止まる、失敗する、またはclaude mcp login --helpが使えないままの場合は、npm install -g @anthropic-ai/claude-code@latestを実行してから再確認します。ネイティブ版の更新にはTTYが必要になることがあります。

python3 -c 'import pty,sys; pty.spawn(sys.argv[1:])' claude update

インストーラーがOSや管理者のパスワードを求めてきた場合は、必要な操作を一度だけ正確に伝え、そのまま待機し、完了後は自動的に処理を再開します。プロキシ環境では、再試行の前にユーザーが実際に使っているHTTPS_PROXYを設定してください。

マーケットプレイスの追加が遅い場合

claude plugin marketplace addは時間のかかるクローン処理です。大きなリポジトリに見合ったタイムアウトを設定して開始し、何度も起動し直すのではなくプロセスをポーリングします。エラーで終了した場合や、十分なタイムアウトを超えて明らかに停止している場合を除き、実行中のプロセスを最後まで待ちます。マーケットプレイスの追加を同時に複数実行しないでください。

プロセスが生きていて出力がないだけなら、そのまま待ちます。実行環境のタイムアウトが短い場合は、バックグラウンドまたは長時間実行できるシェルで動かして出力をログに記録し、プロセスの状態とログの両方をポーリングします。再試行は、前のプロセスが終了してからにしてください。

マーケットプレイスの追加がネットワークで失敗する場合

タイムアウト、TLS/DNSの失敗、fatal: early EOF、そして紛らわしいfatal: Invalid path ...は、たいていGitHubからの転送が中断したことを示しており、リポジトリのファイル名が不正なわけではありません。インストール処理は続けたまま、間隔を空けながら再試行します。

ユーザーが既にプロキシを使っている場合は、それをそのまま利用します。HTTPS_PROXYとHTTP_PROXYを読み取るか、実行中のプロキシツールと実際のポートを特定してください。ローカルでよく使われるポートは7890・7897・1080・8080・8888ですが、当てずっぽうで選んだり、誤ったプロキシ設定を残したりしないでください。

# macOS / Linux example; substitute the user's actual proxy
HTTPS_PROXY=http://127.0.0.1:7890 ALL_PROXY=http://127.0.0.1:7890 claude plugin marketplace add https://github.com/ChatCut-Inc/agent-plugin.git#main

# Windows PowerShell example
$env:HTTPS_PROXY='http://127.0.0.1:7890'; $env:ALL_PROXY=$env:HTTPS_PROXY; claude plugin marketplace add https://github.com/ChatCut-Inc/agent-plugin.git#main

マーケットプレイスの完全なクローンが何度も切断される場合は、別の長時間実行プロセスとして浅いクローンを行い、完了までポーリングしてから、ローカルパスを追加してインストールします。

git clone --depth 1 --branch main https://github.com/ChatCut-Inc/agent-plugin.git
claude plugin marketplace add /path/to/agent-plugin
claude plugin install chatcut@chatcut-inc

マーケットプレイスの追加がprogram not foundを返す場合は、git --versionを確認します。可能な限りbrew install git・winget install Git.Git・apt-get install -y git・dnf install -y gitで非対話的にGitをインストールし、PATHに含まれていることを確認してから再試行してください。避けられないOSインストーラーの確認画面が出た場合は、そのまま待ちます。

ログインでstdinが端末ではないと表示される場合

プラグインのログインスクリプトは自前でPTYを起動します。claude mcp loginを直接呼び出さず、通常の手順どおりに実行してください。

どうしても直接ログインする必要があり、python3も使えない場合は、プラットフォームごとのscriptの書式を使います。

# macOS (BSD script)
script -q /tmp/chatcut-login.log claude mcp login plugin:chatcut:chatcut &

# Linux (util-linux script)
script -qc "claude mcp login plugin:chatcut:chatcut" /tmp/chatcut-login.log &

一方のOSのscriptの書き方を、もう一方にそのまま持ち込まないでください。

Windowsではまず、python3が使えるシェルからPTYで包んだログインコマンドの実行を試みます。

python3 -c 'import pty,sys; pty.spawn(sys.argv[1:])' claude mcp login plugin:chatcut:chatcut > /tmp/chatcut-login.log 2>&1 &

そのシェルでpython3やコマンドを実行できない場合は、cmd.exe /d /c where claudeを確認したうえで、使い捨ての実コンソールを使い、出力を記録します。

Start-Process cmd -ArgumentList '/c','claude mcp login plugin:chatcut:chatcut > %TEMP%\chatcut-login.log 2>&1'

出力をリダイレクトしているため、コンソールには何も表示されないことがあります。$env:TEMP\chatcut-login.logをポーリングし、そのまま開ける認可URLが現れたらすぐに開いて、ポーリングを続けてください。

古いChatCut MCPサーバーがプラグインと競合する場合

claude mcp listで、chatcutという名前のスタンドアロンサーバーと、プラグインが管理するplugin:chatcut:chatcutを見分けます。claude mcp remove chatcutで削除するのはスタンドアロンの設定だけにし、そのあとclaude mcp get plugin:chatcut:chatcutが引き続き解決できることを確認します。後片付けのつもりで名前空間付きのプラグインサーバーを削除してはいけません。

ログインがタイムアウトする、または5xxが返る場合

ログインがAuthentication timeoutを出力した場合は、すぐにログアウトを実行し、新しいログインプロセスを1つだけ起動して、新しい認可URLを表示し、ポーリングを再開します。ログインを同時に複数実行しないでください。

認証が成功する前に、OAuthのディスカバリー、登録、コールバック処理、トークン交換の途中で返るHTTP 502などの5xxは、再試行すれば解消するサービス側の障害です。認証情報が誤っているわけでも、再インストールが必要なわけでもありません。実行中のログインプロセスが終了するのを待ち、間隔を空けて再試行します。必要に応じて、到達性を確認することもできます。

curl -fsS https://api.chatcut.io/.well-known/oauth-authorization-server

Windowsではcurl.exeを使います。ディスカバリーが成功しても、そのエンドポイントに到達できることが分かるだけです。ログインプロセスが認証済みの行を出力するまで待ち続けてください。

`claude mcp login`が存在しない場合

前述の復旧手順でClaude Codeをアップグレードします。非対話的シェルのエラーは擬似端末でのラップで解決できるため、アプリのUIに頼る必要があるのはCLIが古い場合だけです。

2つのアップグレード方法がどちらも失敗したという明確な証拠を押さえたうえで、初めてユーザーに/mcpと入力し、chatcut（plugin:chatcut:chatcut）を選び、Authenticateを選ぶよう伝えます。その間もclaude mcp get plugin:chatcut:chatcutのポーリングを続け、認証が使えるようになったら自動的に処理を再開してください。

確認結果が分かりにくい、またはツールの応答が遅い場合

claude mcp getは、OAuthが成功する前でもConnectedと表示することがあります。ログインが成功する前にNeeds authenticationと出た場合は、ログインの手順に戻ります。Connected · tools fetch failedやRequest timed outは、たいていバックエンドが一時的に遅いだけです。これを理由に再インストールしたり、作業を止めたりしないでください。

ログイン出力で認証済みが確認できたあとでも、ツール一覧の取得が遅いと状態が一時的にNeeds authenticationへ戻ることがあり、バックエンドのウォームアップ中は新しいセッションでの最初の呼び出しがタイムアウトすることもあります。読み込みや呼び出しを再試行すれば十分で、ログインをやり直す必要はありません。本当の認証エラーとみなすのは、ChatCutのツールがタイムアウトではなくconnector authentication is missingを繰り返し明示的に返す場合だけです。

更新に失敗したときの復旧手順

通常の更新コマンドは次のとおりです。

claude plugin marketplace update chatcut-inc
claude plugin update chatcut@chatcut-inc

更新に失敗した場合は、上記のCLI・長時間実行のマーケットプレイス処理・ネットワーク・プロキシのうち該当する復旧手順を適用し、そのうえで確認をやり直します。更新後のツールも新しいセッションでしか読み込まれません。/reload-pluginsを実行したり、ユーザーに実行させたりしないでください。