トラブルシューティング

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/

解決策： Start your dev server with the --host flag set to 0.0.0.0 so it listens on all network interfaces, making it reachable from within the Docker container:

# 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）はホストにインストールされている必要があります。欠落している場合、またはインストールされているバージョンがサーバーでシップされる Playwright バージョンの Chromium リビジョンと一致しない場合、Chromium が起動できなかったというエラーでサーバーは起動に失敗します（または最初のスキャンで失敗します）。

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

標準的な修正

axe MCP サーバーが出荷する Playwright バージョンに一致する Chromium リビジョンをインストールしてください — 現在の1.60.0。Playwright をそのバージョンに固定すると、npx playwrightが解決されて新しいリリースに紐付くことを防げます。

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 バイナリがホストにすでにある場合、AXE_CHROME_PATH環境変数をそのバイナリに設定することで Playwright のインストール全体をスキップできます。これは、Playwright のダウンロードがブロックされている（制限されたネットワーク、プロキシ）場合や、システム依存のインストールがオプションではない場合に、最も迅速な解決策になることが多いです。要件についてはAXE_CHROME_PATHを参照してください — ブランド付き Google Chrome デスクトップ版 137+ はサポートされておらず、値は.appバンドルではなく実行可能なバイナリである必要があります。

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

Playwright は各 Playwright バージョンに特定の Chromium リビジョンを固定し、そのリビジョンは時間と共に変化します。ブラウザバイナリを npm パッケージにバンドルすると、サイズが大幅に増加し、パッケージが1つのプラットフォームのバイナリに縛られ、Playwright が固定リビジョンを更新するとすぐに陳腐化します。 代わりに Playwright 経由で Chromium をインストールすると、インストールされたバージョンが期待する正確なリビジョンを、対象プラットフォームに対して入手できることが保証されます。（Docker ディストリビューションは、既知の単一環境用にビルドされるため、ブラウザをバンドルできます。）

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

axe-mcp-serverをアップグレードすると、現在インストールされているものより新しい新しい Chromium リビジョンを固定する新しい Playwright バージョンが含まれる可能性があります。そのような場合、アップグレード後に同じ起動エラーが再び発生する可能性があります。 修正方法は同じで、アップグレードされたサーバーでシップする Playwright バージョンを使用してインストールを再実行し、Chromium が一致するようにします。

npx playwright@1.60.0 install chromium

経験則として、axe-mcp-serverをアップグレードし、起動時に Chromium の不一致をサーバーが報告するたびに、現在のリリースが出荷する Playwright バージョンを使用してこのコマンドを再実行してください。

認証エラー

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 が正しいことを確認してください
  • If your token has expired mid-session, restart the MCP server connection in your client (e.g., restarting Claude Code, toggling the server off and on in Cursor's MCP settings, or clicking VS Code's CodeLens "Restart" button directly above the axe MCP Server entry in mcp.json) to obtain a fresh token
  • 完全な OAuth トラブルシューティング手順については認証を確認してください

ヘルプを得る

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

  1. 詳細なエラーメッセージを確認するために MCP クライアントの開発者コンソール/ログを確認してください（例：VS Code 開発者コンソール、Cursor の開発者ツール、または Claude Code の--debug出力）。
  2. サーバーログを確認してください — Dockerコンテナのログ、またはnpm配布を使用している場合はMCPクライアントのログ
  3. 次の情報を含めてhelpdesk@deque.comでサポートチームにご連絡ください：
    • MCP クライアントとそのバージョン
    • ご利用のDockerバージョン（Docker配布）またはNode.jsバージョン（npm配布）
    • エラーの完全なメッセージ
    • 問題を再現するための手順

Is this page helpful?

Help us improve this page

Still need help?