Skip to content

Chrome DevTools for coding agents

docs: add troubleshooting for Claude Code plugin HTTPS clone failures (#1195)

Andrei Hodorogd082ca4ecd35
diff --git a/README.md b/README.md
index e04f91eb..508fe2b7 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.
+
</details>
<details>
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index ef299edc..a6b05ee2 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."[email protected]:".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: