> ## Documentation Index
> Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# トラブルシューティング
> Octoparse MCP Serverの接続・認証・タスク実行・エクスポートでよくある問題と、その診断方法をまとめます。
Octoparse MCP Serverのセットアップ中、または利用中に発生しやすい問題の切り分け方をまとめます。
## 接続の問題
### 接続されているがツールが表示されない
認証完了前にクライアントがツール一覧をキャッシュした可能性があります。切断して再接続し、必要であればクライアントを再起動してください。
またサーバーURLが末尾のスラッシュなしで正確に `https://mcp.octoparse.com` であることを確認してください。
## 認証の問題
### OAuth認証が失敗またはループする
ブラウザのタブを閉じて、MCPクライアントから接続フローを再試行してください。
問題が続く場合は、`octoparse.com` のCookieをクリアして再試行してください。
### OAuthは成功したがツール呼び出しが失敗する
OAuthの成功は認証が通過したことを意味するだけです。トークンが期限切れになっているか、アカウントに必要な権限がない可能性があります。
切断して再接続し、トークンを更新してみてください。
### APIキーが見つからない、または無効
MCPサーバーが有効なAPIキーを認識できない場合、認証エラーが発生します。
よくあるエラーメッセージ：
```text theme={null}
Unauthorized
Invalid API key
Authentication failed
401 Unauthorized
Missing API key
```
APIキーが有効であること、削除または再生成されていないことを確認してください。
環境変数を使用している場合は、MCPサーバーを起動するシェルやランタイムで、その変数が実際に参照できる状態かを確認します。
```bash theme={null}
echo $OCTOPARSE_API_KEY
```
出力が空の場合は、サーバーを起動する前にAPIキーを設定し直してください。
```bash theme={null}
export OCTOPARSE_API_KEY="your-api-key"
```
APIキーをGit、スクリプト、スクリーンショット、共有ログ、公開のissueなどに含めないでください。
### ターミナルでは動くがMCPクライアントでは認証に失敗する
MCPクライアントの中には、対話型ターミナルの環境変数を引き継がないものがあります。
手動で起動したときは動作し、MCPクライアント経由では失敗する場合は、クライアント側の設定を確認し、APIキーがサーバープロセスに渡されているかを確認してください。
環境変数を更新したあとは、MCPクライアントを再起動します。
## サーバー起動の問題
### MCPサーバーが起動しない
起動に失敗する場合は、コマンド、作業ディレクトリ、Node.jsのバージョン、環境変数を確認します。
まずターミナルでサーバーのコマンドを直接実行してみてください。これでMCPクライアント側の設定の問題か、サーバー自体の実行時の問題かを切り分けられます。
```bash theme={null}
node --version
npm --version
```
MCPクライアントが使用しているコマンドが、ターミナルで動作したコマンドと一致しているかを確認してください。
### コマンドが見つからない
MCPクライアントが「コマンドが見つからない」と報告する場合は、絶対パスを指定するか、パッケージがインストールされているかを確認します。
クライアントがシェルと同じ `PATH` を使用していない場合、シェルでは動くコマンドがMCPクライアントでは失敗することがあります。
## タスクへのアクセスの問題
### タスクが見つからない
タスクIDが正しくない場合や、認証中のアカウントにそのタスクへのアクセス権がない場合、タスクが見つからないというエラーになります。
以下を確認してください。
* タスクIDが正しくコピーされているか
* そのタスクが、認証しているOctoparseアカウントに属しているか
* タスクが削除されていないか
* APIキーが対象のワークスペース・アカウントのものか
### タスクが1件も返らない
タスク検索の結果が空になる場合は、まずAPIキーとアカウントのアクセス権を確認してください。そのうえで、検索条件を広げるか、キーワードを指定せずに一覧を取得してみます。
## タスク実行の問題
### `search_templates` は動作するが `execute_task` が失敗する
最も一般的な原因は、選択したテンプレートがローカル実行のみをサポートしていることです。その場合は、Octoparseデスクトップクライアントから実行してください。
もう一つの一般的な原因は、アカウントのクラウド実行クレジットが不足していることです。
### タスクが起動しない
タスク定義が未対応である、すでに実行中である、アカウントに実行権限がない、といった場合にタスクは起動しません。
まずOctoparse側でタスクの状態を確認し、そのうえでMCPクライアントから再試行してください。
古いワークフローで作成されたタスクの場合は、現在のOctoparseアプリで作り直すか更新してから、自動化経由で実行してください。
### 実行は始まるがデータが返らない
実行は成功したのにエクスポートでデータが得られない場合は、タスクが完了しているか、選択した実行結果にデータが含まれているかを確認します。
よくある原因：
* タスクがまだ実行中である
* 選択したロットIDにデータが含まれていない
* タスクは完了したが、該当するレコードが1件もなかった
* 実行の完了前にエクスポートを要求した
## エクスポートの問題
### `export_data` が空を返す
まず次の2点を確認してください。
1. タスクが実際に完了しているかどうか。`search_tasks` を使用してステータスを確認してください。
2. アカウントにそのタスクのデータへのアクセス権限があるかどうか。
空のエクスポートは、選択した実行結果に抽出レコードが存在しないか、抽出の完了前にエクスポートを要求した場合に発生します。タスク履歴を確認してから、正しい実行結果を指定して再度エクスポートしてください。
### エクスポートが失敗する
タスクが完了していること、使用しているツールがそのエクスポート形式に対応していることを確認してください。
ロットIDを指定できるコマンドやツールを使う場合は、そのロットIDが同じタスク・同じ実行履歴のものであることを確認します。
## レート制限と一時的な失敗
リクエストが断続的に失敗する場合は、少し待ってから再試行してください。ネットワークの問題、タスクキューの遅延、バックエンドの一時的なエラーによって発生することがあります。
繰り返し失敗する場合は、以下を記録しておくと切り分けが早くなります。
* MCPクライアント名とバージョン
* MCPサーバーのバージョン
* 実行したツール呼び出しまたはプロンプト
* タスクID
* エラーメッセージ
* 同じタスクがOctoparse上で直接実行できるかどうか
ログを共有する前に、APIキー、アクセストークン、Cookie、個人情報を削除してください。
## 問い合わせ時に必要な情報
問い合わせの際は、以下の情報を含めてください。
* MCPクライアント名
* MCPサーバーのバージョン
* OS
* Node.jsのバージョン
* 失敗したツール名
* エラーメッセージの全文
* タスクID、または機密情報を除いた例
* MCP経由ではなくOctoparse上で同じタスクが動作するかどうか