Claude Code MCP 配置问题修复指南（Windows 版）

更新日志：新增 HTTP 类型 MCP 配置说明及百度搜索实战案例

---

📌 问题现象

当你满心欢喜地在 Claude Code 中输入 /mcp 想要查看已配置的 MCP 服务器时，却看到了这样的提示：

> /mcp
No MCP servers configured. Please run /doctor if this is unexpected.

但是，你明明已经检查过 ~/.claude/settings.json 文件，配置看起来完全正确：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "D:/DATA"]
    }
  }
}

这到底是怎么回事？ 🤔

---

🔍 根本原因分析

经过深入研究，我发现问题出在以下几个方面：

1️⃣ 配置方式错误

MCP 服务器不应该直接编辑 settings.json 文件，而是应该使用 claude mcp add 命令来添加。

2️⃣ Windows 特有问题

在 Windows 系统上，npx 命令需要特殊处理——必须用 cmd /c 进行包装，否则会导致连接失败。

3️⃣ HTTP 类型 MCP 需要额外配置

对于 HTTP/HTTPS 类型的 MCP 服务，如果需要认证，必须用 -H 参数传递 Header 信息。

---

✅ 完整解决方案

步骤 1：使用正确的命令行配置方式

📁 STDIO 类型 MCP（本地进程）

# 添加文件系统 MCP（访问 D:/DATA 目录）
claude mcp add -t stdio -s user filesystem -- cmd /c "npx -y @modelcontextprotocol/server-filesystem D:/DATA"

# 添加 Puppeteer MCP（浏览器自动化）
claude mcp add -t stdio -s user puppeteer -- cmd /c "npx -y @modelcontextprotocol/server-puppeteer"

# 添加 Chrome DevTools MCP
claude mcp add -t stdio -s user chrome-devtools -- cmd /c "npx -y chrome-devtools-mcp@latest"

# 添加 Gitee MCP（带环境变量）
claude mcp add -t stdio -s user gitee -- cmd /c "npx -y @gitee/mcp-gitee" -e GITEE_ACCESS_TOKEN=your_token_here

🌐 HTTP 类型 MCP（远程服务）

# 基础 HTTP 服务器（无认证）
claude mcp add -t http -s user <服务名称> <URL>

# HTTP 服务器（带 Bearer Token 认证）
claude mcp add -t http -s user baidu-web-search "https://qianfan.baidubce.com/v2/tools/web-search/mcp" -H "Authorization: Bearer your_api_key_here"

# 多个 Header 头
claude mcp add -t http -s user my-mcp "https://example.com/mcp" -H "Authorization: Bearer token1" -H "X-Custom-Header: value"

步骤 2：验证配置是否成功

# 查看已配置的所有服务器
claude mcp list

# 预期输出示例
gitee: cmd /c npx -y @gitee/mcp-gitee - ✓ Connected
baidu-web-search: https://qianfan.baidubce.com/v2/tools/web-search/mcp (HTTP) - ✓ Connected
filesystem: ✓ Connected
puppeteer: ✓ Connected

# 查看特定服务器详情
claude mcp get <服务器名称>

# 删除不需要的服务器
claude mcp remove <服务器名称>

步骤 3：在 Claude Code 中确认

重启 Claude Code 后，输入 /mcp 命令，现在应该能看到已连接的 MCP 服务器列表了！🎉

---

🚀 实战案例：百度搜索 MCP

背景介绍

百度搜索 MCP 采用 streamableHttp 类型，需要 API Key 进行认证。这是一个非常实用的 MCP，可以让 Claude 实时搜索网络信息。

完整安装步骤

1. 获取百度 API Key

首先需要从百度智能云获取 API Key（格式类似：bce-v3/ALTAK-xxxxxxxxxxxx）

2. 添加 MCP 服务器

# 添加百度搜索 MCP（带 Authorization Header）
claude mcp add -t http -s user baidu-web-search "https://qianfan.baidubce.com/v2/tools/web-search/mcp" -H "Authorization: Bearer bce-v3/ALTAK-xxxxxxxxxxxx"

3. 验证连接状态

claude mcp list

# 成功输出示例
baidu-web-search: https://qianfan.baidubce.com/v2/tools/web-search/mcp (HTTP) - ✓ Connected

4. 测试使用

在 Claude Code 中直接问：

"搜索一下 Claude Code MCP 的最新消息"

Claude 会自动调用百度搜索 MCP，返回实时搜索结果！

---

📂 配置存储位置说明

作用域	存储位置	适用场景
--scope user	~/.claude.json	用户级配置，所有项目可用
--scope project	.mcp.json	项目级配置，可共享给团队
--scope local	~/.claude.json (项目路径下)	仅当前项目，不共享

---

📝 常用 MCP 命令速查表

# 添加 stdio 类型服务器
claude mcp add -t stdio -s user <名称> -- <命令>

# 添加 HTTP 类型服务器
claude mcp add -t http -s user <名称> <URL>

# 添加带认证的 HTTP 服务器
claude mcp add -t http -s user <名称> <URL> -H "Header: value"

# 列出所有服务器
claude mcp list

# 查看服务器详情
claude mcp get <名称>

# 删除服务器
claude mcp remove <名称>

# 在 Claude Code 内查看状态
/mcp

# 查看帮助信息
claude mcp add --help

---

⚠️ Windows 特别注意事项

在 Windows 系统上，使用 npx 启动的 MCP 服务器必须用 cmd /c 包装：

# ❌ 错误写法 - 会导致 "Connection closed" 错误
claude mcp add -t stdio myserver -- npx -y @some/package

# ✅ 正确写法
claude mcp add -t stdio myserver -- cmd /c "npx -y @some/package"

原因：Windows 的命令行解析机制与 Linux/Mac 不同，直接调用 npx 会导致进程管理问题。

---

🔧 HTTP MCP 连接失败排查指南

如果遇到 HTTP MCP 连接失败，请按以下步骤排查：

1️⃣ 检查 URL 是否正确

确认 MCP 服务地址无误，注意协议（http/https）和端口号。

2️⃣ 检查认证信息

确认 Header 配置正确，特别是 -H 参数的格式：

-H "Authorization: Bearer your_token"  # ✅ 正确
-H Authorization: Bearer your_token     # ❌ 错误（缺少引号）

3️⃣ 测试网络连通性

# 测试 endpoint 是否可访问
curl -I https://qianfan.baidubce.com/v2/tools/web-search/mcp

# 带认证测试
curl -H "Authorization: Bearer your_key" https://qianfan.baidubce.com/v2/tools/web-search/mcp

4️⃣ 检查 API Key 权限

确认 API Key 有访问该 MCP 服务的权限，有些服务需要单独开通。

---

🐛 相关环境变量问题

如果遇到 coding_plan_model_not_supported 等错误，可能是因为环境变量冲突：

# 检查当前环境变量
echo %ANTHROPIC_AUTH_TOKEN%
echo %ANTHROPIC_API_KEY%
echo %ANTHROPIC_BASE_URL%

# 检查用户环境变量（注册表）
reg query "HKCU\Environment" /s

常见冲突来源：

• CodeBuddy CN
• Obsidian terminal
• 其他 AI 编码工具

解决方法：清理不必要的环境变量，或在新终端中测试。

---

🛠️ 常用 MCP 服务器推荐

MCP 名称	类型	命令/URL	功能说明
文件系统	stdio	@modelcontextprotocol/server-filesystem	访问和管理本地文件
Puppeteer	stdio	@modelcontextprotocol/server-puppeteer	浏览器自动化操作
Chrome DevTools	stdio	chrome-devtools-mcp@latest	Chrome 开发者工具集成
百度搜索	http	https://qianfan.baidubce.com/v2/tools/web-search/mcp	实时网页搜索
Gitee	stdio	@gitee/mcp-gitee	码云代码托管操作
GitHub	stdio	@modelcontextprotocol/server-github	GitHub API 集成
PostgreSQL	stdio	@modelcontextprotocol/server-postgres	数据库查询

---

📚 参考文档

• Claude Code MCP 官方文档
• MCP 协议官网
• MCP 服务器列表
• 百度智能云 MCP 服务

---

💡 总结与最佳实践

错误做法 ❌	正确做法 ✅
直接编辑 settings.json	使用 claude mcp add 命令
npx -y @package (Windows)	cmd /c "npx -y @package" (Windows)
忽略 MCP 授权提示	首次启动时选择 “Allow”
HTTP MCP 不带认证信息	使用 -H 参数传递 Header
配置后不重启 Claude Code	重启后输入 /mcp 验证

🎯 快速检查清单

• 使用 claude mcp add 命令添加，而非直接编辑配置文件
• Windows 系统上使用 cmd /c 包装 npx 命令
• HTTP MCP 带认证时使用 -H 参数
• 添加后运行 claude mcp list 验证
• 重启 Claude Code 后输入 /mcp 确认连接状态

---

🙋 常见问题 FAQ

Q: 配置后仍然显示 “No MCP servers configured”？
A: 确保你重启了 Claude Code，配置只在启动时加载。

Q: HTTP MCP 显示 “Connection failed”？
A: 检查网络连接、URL 正确性和 API Key 是否有效。

Q: 如何更新 MCP 服务器？
A: 先 claude mcp remove <name>，再重新 claude mcp add。

Q: 可以同时配置多个 MCP 吗？
A: 可以！Claude Code 支持同时运行多个 MCP 服务器。

---

希望这篇指南能帮你解决 MCP 配置问题！如果还有其他问题，欢迎在评论区留言交流。 🚀