# Claude Codeへの導入手順｜ChatCut Source: [Claude Codeへの導入手順｜ChatCut]() Content index: [llms.txt]() ## Claude Codeへの導入手順 ChatCutの公開マーケットプレイスから、ChatCutが管理するClaude Codeプラグインを`main`に固定してインストールします。 ## インストールとログイン まず、次の2つのインストールコマンドをこの順番で実行します。 ```text claude plugin marketplace add https://github.com/ChatCut-Inc/agent-plugin.git#main claude plugin install chatcut@chatcut-inc ``` マーケットプレイスの追加コマンドは大きなリポジトリをクローンするため、数分かかることがあります。長時間実行のプロセスとして十分なタイムアウトを設定し、終了するまでポーリングしてください。しばらく出力がなくても失敗ではありません。通常の短いコマンド用のタイムアウトが切れただけで中断しないでください。 このマシンで以前ChatCutを使っていた可能性がある場合は、既存のスタンドアロンMCPサーバー設定が残っていないか確認しておくとよいでしょう。 ```text claude mcp get chatcut ``` このコマンドで`chatcut`と完全に一致する名前のサーバーが見つかった場合は、ログインする前に古いスタンドアロン設定を削除します。 ```text claude mcp remove chatcut ``` `plugin:chatcut:chatcut`は削除しないでください。これは新しくインストールしたプラグインが管理するサーバーです。`claude mcp get chatcut`がそのようなサーバーは存在しないと表示した場合は、そのまま次に進みます。 続いて、プラグインのログインスクリプトでChatCut MCPサーバーにログインします。 ```text 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の認可ページを開きます。 認証が完了したら、インストール結果を確認します。 ```text 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点を確認します。 ```text claude --version claude mcp login --help ``` 現在のシェルで`claude`を解決できない場合は、まず`command -v claude`と`~/.local/bin/claude`を確認します。Windowsでは、次のコマンドでシェルをまたいで探します。 ```text powershell.exe -NoProfile -Command "(Get-Command claude -ErrorAction SilentlyContinue).Source" cmd.exe /d /c where claude ``` 実行ファイルが見つかったら直接呼び出してください。特定のシェルの`PATH`が古い、あるいは異なるというだけで再インストールしないでください。Claude Code Desktopがあるからといって、ターミナルのCLIが存在するとは限りません。 ターミナルから使える実行ファイルがまったく存在しない場合にのみ、Anthropic公式のインストーラーを使います。 ```text # 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が必要になることがあります。 ```text 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`ですが、当てずっぽうで選んだり、誤ったプロキシ設定を残したりしないでください。 ```text # 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 ``` マーケットプレイスの完全なクローンが何度も切断される場合は、別の長時間実行プロセスとして浅いクローンを行い、完了までポーリングしてから、ローカルパスを追加してインストールします。 ```text 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`の書式を使います。 ```text # 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で包んだログインコマンドの実行を試みます。 ```text 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`を確認したうえで、使い捨ての実コンソールを使い、出力を記録します。 ```text 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は、再試行すれば解消するサービス側の障害です。認証情報が誤っているわけでも、再インストールが必要なわけでもありません。実行中のログインプロセスが終了するのを待ち、間隔を空けて再試行します。必要に応じて、到達性を確認することもできます。 ```text 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`のポーリングを続け、認証が使えるようになったら自動的に処理を再開してください。 ### APIまたはMCPのリクエストで403が返る場合 403が返り続ける間は、自動再試行を一時停止してください。現在のプロジェクトとローカルのメディアはそのまま残します。エラー内容、おおよその発生時刻とタイムゾーン、そのときに使用していたパブリックIPアドレスを添えて、[team@chatcut.io](mailto:team@chatcut.io)に連絡してください。すでに記録済みのリクエストIDがあれば、それも含めます。報告のためにインポートや生成をやり直す必要はありません。 403が返った場合は、アクセスルールやレート制限ルールの確認が必要です。認証情報が間違っていると断定できるわけではありません。アクセスが復旧したら、元のタスクの状態を確認してから再開してください。 ### 確認結果が分かりにくい、またはツールの応答が遅い場合 `claude mcp get`は、OAuthが成功する前でも`Connected`と表示することがあります。ログインが成功する前に`Needs authentication`と出た場合は、ログインの手順に戻ります。`Connected · tools fetch failed`や`Request timed out`は、たいていバックエンドが一時的に遅いだけです。これを理由に再インストールしたり、作業を止めたりしないでください。 ログイン出力で認証済みが確認できたあとでも、ツール一覧の取得が遅いと状態が一時的に`Needs authentication`へ戻ることがあり、バックエンドのウォームアップ中は新しいセッションでの最初の呼び出しがタイムアウトすることもあります。ツールの検出や、そのほかの読み取り専用の読み込みは、待機時間を徐々に延ばしながら再試行してください。タイムアウトしたツール呼び出しがプロジェクトを変更したり、生成を開始したりした可能性がある場合は、繰り返す前に元のタスクの状態を確認してください。ログインをやり直す必要はありません。本当の認証エラーとみなすのは、ChatCutのツールがタイムアウトではなく`connector authentication is missing`を繰り返し明示的に返す場合だけです。 ## 更新に失敗したときの復旧手順 通常の更新コマンドは次のとおりです。 ```text claude plugin marketplace update chatcut-inc claude plugin update chatcut@chatcut-inc ``` 更新に失敗した場合は、上記のCLI・長時間実行のマーケットプレイス処理・ネットワーク・プロキシのうち該当する復旧手順を適用し、そのうえで確認をやり直します。更新後のツールも**新しいセッション**でしか読み込まれません。`/reload-plugins`を実行したり、ユーザーに実行させたりしないでください。