当前位置：首页 > news >正文

Claude Code PowerShell 安装 MCPs 方法：以 Puppeteer 为例

news 2025/7/27 6:35:22

Claude Code PowerShell 安装 MCPs 方法：以 Puppeteer 为例

概述

在 Windows PowerShell 环境中为 Claude Code 安装 MCP (Model Context Protocol) 服务器经常遇到各种问题。本文基于实际解决经验，详细介绍如何成功安装和配置 Puppeteer MCP 服务器。

常见问题及根本原因

主要错误类型

路径问题：/usr/bin/bash: Files\Git\bin\bash.exe: No such file or directory
连接失败：✗ Failed to connect
包已弃用：@modelcontextprotocol/server-puppeteer@2025.5.12: Package no longer supported

根本原因分析

官方包已弃用：@modelcontextprotocol/server-puppeteer 不再维护
路径配置错误：Windows 环境下 bash 路径解析问题
依赖冲突：npx 执行环境与 Windows 路径不兼容

✅ 正确解决方案（已验证有效）

第一步：选择正确的替代包

使用社区维护的 puppeteer-mcp-server 替代官方已弃用的包：

npm install -g puppeteer-mcp-server

第二步：找到正确的安装路径

npm list -g puppeteer-mcp-server

示例输出：

B:\nvm\v22.17.0 -> .
└── puppeteer-mcp-server@0.7.2

第三步：使用完整 Node 路径配置

❌ 错误方法（会失败）：

claude mcp add puppeteer -s user -- npx -y puppeteer-mcp-server
claude mcp add puppeteer -s user -- puppeteer-mcp-server

✅ 正确方法（已验证）：

claude mcp add puppeteer -s user -- node "B:\nvm\v22.17.0\node_modules\puppeteer-mcp-server\dist\index.js"

第四步：验证连接状态

claude mcp list

成功输出：

Checking MCP server health...
puppeteer: node B:\nvm\v22.17.0\node_modules\puppeteer-mcp-server\dist\index.js - ✓ Connected

🔧 故障排除指南

Debug 模式启动

使用 debug 模式可以看到详细错误信息：

claude --mcp-debug

常见错误及解决方案

1. bash 路径错误

[ERROR] MCP server "puppeteer" Server stderr: /usr/bin/bash: Files\Git\bin\bash.exe: No such file or directory

解决方案：使用完整的 node 路径，避免 bash 路径解析问题。

2. 连接超时

✗ Failed to connect

解决方案：

确保 Node.js 正确安装
检查防火墙设置
验证包路径正确性

3. 权限问题

EPERM: operation not permitted

解决方案：

以管理员身份运行 PowerShell
检查文件权限设置

📦 其他 MCP 服务器安装示例

基于成功的 Puppeteer 安装经验，其他 MCP 服务器的安装模式：

文件系统操作

npm install -g @some-org/filesystem-mcp
claude mcp add filesystem -s user -- node "路径/to/node_modules/@some-org/filesystem-mcp/dist/index.js"

数据库连接

npm install -g sqlite-mcp-server
claude mcp add sqlite -s user -- node "路径/to/node_modules/sqlite-mcp-server/dist/index.js"

🧪 测试验证

成功安装后，可以测试 Puppeteer 功能：

// 使用 MCP 工具
puppeteer_navigate: 导航到网页
puppeteer_screenshot: 截取屏幕截图
puppeteer_click: 点击元素
puppeteer_fill: 填写表单

💡 最佳实践

优先使用社区维护的包：避免官方已弃用的包
使用完整路径：避免依赖系统路径解析
开启 debug 模式：快速定位问题根源
定期更新依赖：保持包的最新版本

📝 配置文件示例

成功配置后的 .claude.json 片段：

{"mcpServers": {"puppeteer": {"type": "stdio","command": "node","args": ["B:\\nvm\\v22.17.0\\node_modules\\puppeteer-mcp-server\\dist\\index.js"],"env": {}}}
}