トラブルシューティング

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard
Not for use with personal data

このページでは、 Docker および npm ディストリビューション共通の問題を扱います。どちらか一方のディストリビューションにのみ適用される問題は適切にラベル付けされています。

サーバーが起動しない

  • Docker の実行を確認してください（Docker ディストリビューションの場合）、または Chromium がインストールされていることを確認してください（npm ディストリビューションの場合—詳細は Chromium インストールを参照）
  • 認証情報が正しいことを確認してください。いずれか一方の AXE_API_KEY または AXE_ACCESS_TOKENを設定しますが、両方を設定するとサーバーは起動に失敗します。
  • axe MCP サーバーにアクセスできることを確認してください（必要に応じてサポートに連絡してください）。

スキャンタイムアウト

  • を増やしてください BROWSER_TIMEOUT_MS 複雑なページの場合
  • ターゲット URL がネットワークからアクセス可能であることを確認してください。
  • ネットワーク接続性の問題を確認してください。

ローカル開発サーバースキャンが失敗 ERR_CONNECTION_REFUSED

これは Docker ディストリビューション に適用されます—npm ディストリビューションではサーバーがホストで直接実行され、 localhost 通常のサービス

にアクセス可能です。 analyze ツールが net::ERR_CONNECTION_REFUSED エラーを示してローカルで実行中の開発サーバーをスキャンしようとして失敗する場合、これはおそらく axe MCP サーバーが Docker コンテナ内で実行され、ホストマシンにのみバインドされたサービスに到達できないためです。 localhost （つまり、 127.0.0.1など）

エラー例：

net::ERR_CONNECTION_REFUSED at http://192.168.65.2:5173/

解決策： 開発サーバーを起動してください、 --host フラグを 0.0.0.0 に設定し、すべてのネットワークインターフェースでリッスンするようにします。これにより Docker コンテナ内からアクセス可能になります：

# Vite
npm run dev -- --host=0.0.0.0

# Webpack (webpack-dev-server)
npm run dev -- --host=0.0.0.0

Docker に関する問題

  • Docker デーモンが実行されていることを確認してください。
  • Docker の権限を確認してください。
  • Docker イメージのダウンロードのためのネットワーク接続性を確認してください。
  • Docker に十分なメモリがあることを確認してください、 docker system prune

Chromium インストール（npm）

このセクションは npm ディストリビューションに適用されます。Docker ディストリビューションには独自のブラウザがバンドルされているため、Docker ユーザーは Chromium をインストールする必要がなく、ここで説明されるエラーの影響を受けません。

エラーの意味

axe MCP サーバーは、 Playwrightを介した実際のブラウザを動かしてアクセシビリティスキャンを実行します。npm ディストリビューションでは、そのブラウザである Chromium をホストにインストールする必要があります。インストールされていない場合、もしくはインストールされた Chromium のバージョンがサーバーで提供される Playwright のバージョンが期待する Chromium バージョンと一致しない場合、Chromium を起動できなかったことを示すエラーと共に、サーバーの起動が失敗する（または最初のスキャンで失敗する）ことになります。

これは新規インストール時に予想されるもので、簡単に修正できます。

標準的な修正

Playwright のバージョンに一致する Chromium のバージョンをインストールしてください。現在のところ 1.60.0。Playwright をそのバージョンに固定して、ベア npx playwright がサーバーでサポートされていない Chromium リビジョンに解決されないようにします:

npx playwright@1.60.0 install chromium

その後、MCP サーバー（または MCP クライアント）を再起動して、再試行してください。

Linux のフォローアップ

Linux では、Chromium も存在しないかもしれない多数のシステムライブラリに依存しています。標準の修正後もブラウザーが起動しない場合は、それらの依存関係をインストールしてください:

sudo npx playwright@1.60.0 install-deps chromium

これらの手順を 1 つのコマンドに組み合わせることもできます:

sudo npx playwright@1.60.0 install --with-deps chromium

既にお持ちのブラウザを使用する

ホストに互換性のある Chrome/Chromium バイナリが既にある場合は、Playwright のインストールを完全に回避して、その AXE_CHROME_PATH 環境変数をそのバイナリに設定します。これは通常、Playwright のダウンロードがブロックされている場合（制限付きネットワーク、プロキシ）やシステム依存関係のインストールができない場合の最も速い解決策です。詳細は AXE_CHROME_PATH を参照してください — Branded Google Chrome の安定版 137+ はサポートされず、値は .app バンドルではなく実行可能なバイナリでなければなりません。

なぜ Chromium がバンドルされないのか

Playwright は 特定の Chromium リビジョン を各 Playwright バージョンに固定し、そのリビジョンは時間とともに変わります。npm パッケージにブラウザバイナリをバンドルすると、そのサイズが大幅に増加し、パッケージを 1 つのプラットフォームのバイナリに結び付けることになり、Playwright が固定リビジョンを更新するのと同時に陳腐化します。Playwright を介して Chromium をインストールすることで、インストールしたバージョンが期待する正確なリビジョンを、プラットフォームに応じて入手できます。（Docker ディストリビューションは、単一の既知の環境用に構築されたイメージであるため、ブラウザをバンドルできます。）

axe-mcp-server のアップグレード後の再実行

アップグレードには、 axe-mcp-server 新しい Playwright バージョンが含まれているかもしれません。それは 新しい Chromium リビジョン に固定されることがあります。それが起こると、アップグレード後に同じ起動エラーが再び表示されることがあります。修正は同じです — アップグレードされたサーバーが出荷する Playwright バージョンを使用して再インストールを実行し、Chromium を一致させます:

npx playwright@1.60.0 install chromium

経験則として、現在のリリースが提供する Playwright バージョンを使用して、このコマンドを再実行してください — をアップグレードするたびに、 axe-mcp-server およびサーバーがスタートアップで Chromium の不一致を報告するとき。

認証エラー

API キー

  • API キーが有効で期限切れでないことを確認してください
  • axe アカウントポータルのサブスクリプションに MCP サーバーアクセスが含まれていることを確認してください
  • API キーが「axe MCP Server」製品用に作成されたものであることを確認してください
  • 以下のみが設定されていることを確認してください AXE_API_KEY — が AXE_ACCESS_TOKEN も設定されていると、サーバーはスタートアップで失敗します
  • axe サーバーの URL が正しいことを確認してください — 組織が地域的なプライベートクラウド、またはオンプレミスの axe インスタンスを使用している場合、 AXE_SERVER_URL はインスタンスのベース URL に設定する必要があります。詳細は 設定リファレンス を参照してください。

OAuth

  • 以下のみが設定されていることを確認してください AXE_ACCESS_TOKEN — が AXE_API_KEY も設定されていると、サーバーはスタートアップで失敗します
  • 確認のために、あなたの端末で npx @deque/axe-auth token を実行して有効なトークンを持っていることを確認します。もし、ゼロ以外のコードで終了する場合は、 npx @deque/axe-auth login
  • axe サーバーの URL が正しいことを確認してください
  • トークンがセッション中に期限切れになった場合は、クライアント内で MCP サーバー接続を再起動してください（例: Claude Code を再起動する、Cursor の MCP 設定でサーバーのオフ/オンを切り替える、または mcp.jsonの axe MCP Server エントリーのすぐ上にある VS Code の CodeLens「再起動」ボタンをクリックするなど）。新しいトークンを取得します
  • 詳細については 認証 の完全な OAuth トラブルシューティング手順を参照してください

ヘルプを得る

このトラブルシューティングセクションでカバーされていない問題が発生した場合:

  1. 詳細なエラーメッセージを確認するには、VS Code デベロッパーコンソールを確認してください
  2. サーバーログを確認してください — Dockerコンテナのログ、またはnpm配布を使用している場合はMCPクライアントのログ
  3. サポートチームに連絡するには helpdesk@deque.com へ次の情報をお知らせください:
    • ご利用のVS Codeのバージョン
    • ご利用のDockerバージョン（Docker配布）またはNode.jsバージョン（npm配布）
    • エラーの完全なメッセージ
    • 問題を再現するための手順

Is this page helpful?

Help us improve this page

Still need help?