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