From d8881d6fa4c443039a8df6929f467498f0ab57e6 Mon Sep 17 00:00:00 2001 From: Andrei Hodorog Date: Mon, 16 Mar 2026 11:42:33 +0000 Subject: [PATCH] docs: add troubleshooting for Claude Code plugin HTTPS clone failures When installing chrome-devtools-mcp as a Claude Code plugin, the installation process clones the repository via HTTPS from GitHub. In environments with restricted outbound HTTPS connectivity (corporate firewalls, proxy configurations, or servers with port 443 blocked), this clone operation fails with a timeout error: fatal: unable to access 'https://github.com/ChromeDevTools/chrome-devtools-mcp.git/': Failed to connect to github.com port 443 This commit adds documentation for two workarounds: 1. Redirecting GitHub HTTPS URLs to SSH via git config, which allows users with SSH key authentication to bypass HTTPS restrictions entirely using: git config --global url."git@github.com:".insteadOf "https://github.com/" 2. Installing chrome-devtools-mcp via the Claude Code CLI as an MCP server directly (claude mcp add), which uses npm/npx instead of git clone and avoids the HTTPS requirement altogether, though without the bundled skills that the plugin marketplace provides. The troubleshooting section is added to docs/troubleshooting.md under "Specific problems", and a cross-reference TIP callout is added to the Claude Code plugin installation section in README.md to guide users who encounter this error to the workarounds. --- README.md | 3 +++ docs/troubleshooting.md | 41 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/README.md b/README.md index e04f91eb4..508fe2b72 100644 --- a/README.md +++ b/README.md @@ -156,6 +156,9 @@ Then, install the plugin: Restart Claude Code to have the MCP server and skills load (check with `/skills`). +> [!TIP] +> If the plugin installation fails with a `Failed to clone repository` error (e.g., HTTPS connectivity issues behind a corporate firewall), see the [troubleshooting guide](./docs/troubleshooting.md#claude-code-plugin-installation-fails-with-failed-to-clone-repository) for workarounds, or use the CLI installation method above instead. +
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index ef299edc4..a6b05ee2b 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -126,6 +126,47 @@ Possible workarounds include: } ``` +### Claude Code plugin installation fails with `Failed to clone repository` + +When installing `chrome-devtools-mcp` as a Claude Code plugin (either from the +official marketplace or via `/plugin marketplace add`), the installation may fail +with a timeout error if your environment cannot reach `github.com` on port 443 +(HTTPS): + +``` +Failed to download/cache plugin chrome-devtools-mcp: Failed to clone repository: + Cloning into '...'... + fatal: unable to access 'https://github.com/ChromeDevTools/chrome-devtools-mcp.git/': + Failed to connect to github.com port 443 +``` + +This can happen in environments with restricted outbound HTTPS connectivity, +corporate firewalls, or proxy configurations that block HTTPS git operations. + +**Workaround 1: Use SSH instead of HTTPS** + +If you have SSH access to GitHub configured, you can redirect all GitHub HTTPS +URLs to use SSH by running: + +```sh +git config --global url."git@github.com:".insteadOf "https://github.com/" +``` + +Then retry the plugin installation. This tells git to use your SSH key for all +GitHub operations instead of HTTPS. + +**Workaround 2: Install via CLI instead** + +If the plugin marketplace approach fails, you can install `chrome-devtools-mcp` +as an MCP server directly without cloning the repository: + +```sh +claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest +``` + +This bypasses the git clone entirely and uses npm/npx to fetch the package. Note +that this method installs only the MCP server without the bundled skills. + ### Connection timeouts with `--autoConnect` If you are using the `--autoConnect` flag and tools like `list_pages`, `new_page`, or `navigate_page` fail with a timeout (e.g., `ProtocolError: Network.enable timed out` or `The socket connection was closed unexpectedly`), this usually means the MCP server cannot handshake with the running Chrome instance correctly. Ensure: