Skip to content

Commit 7181501

Browse files
committed
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.
1 parent e6b7a09 commit 7181501

2 files changed

Lines changed: 44 additions & 0 deletions

File tree

README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,9 @@ Then, install the plugin:
156156

157157
Restart Claude Code to have the MCP server and skills load (check with `/skills`).
158158

159+
> [!TIP]
160+
> 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.
161+
159162
</details>
160163

161164
<details>

docs/troubleshooting.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,47 @@ Possible workarounds include:
126126
}
127127
```
128128

129+
### Claude Code plugin installation fails with `Failed to clone repository`
130+
131+
When installing `chrome-devtools-mcp` as a Claude Code plugin (either from the
132+
official marketplace or via `/plugin marketplace add`), the installation may fail
133+
with a timeout error if your environment cannot reach `github.com` on port 443
134+
(HTTPS):
135+
136+
```
137+
Failed to download/cache plugin chrome-devtools-mcp: Failed to clone repository:
138+
Cloning into '...'...
139+
fatal: unable to access 'https://github.com/ChromeDevTools/chrome-devtools-mcp.git/':
140+
Failed to connect to github.com port 443
141+
```
142+
143+
This can happen in environments with restricted outbound HTTPS connectivity,
144+
corporate firewalls, or proxy configurations that block HTTPS git operations.
145+
146+
**Workaround 1: Use SSH instead of HTTPS**
147+
148+
If you have SSH access to GitHub configured, you can redirect all GitHub HTTPS
149+
URLs to use SSH by running:
150+
151+
```sh
152+
git config --global url."git@github.com:".insteadOf "https://github.com/"
153+
```
154+
155+
Then retry the plugin installation. This tells git to use your SSH key for all
156+
GitHub operations instead of HTTPS.
157+
158+
**Workaround 2: Install via CLI instead**
159+
160+
If the plugin marketplace approach fails, you can install `chrome-devtools-mcp`
161+
as an MCP server directly without cloning the repository:
162+
163+
```sh
164+
claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
165+
```
166+
167+
This bypasses the git clone entirely and uses npm/npx to fetch the package. Note
168+
that this method installs only the MCP server without the bundled skills.
169+
129170
### Connection timeouts with `--autoConnect`
130171

131172
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:

0 commit comments

Comments
 (0)