新手上路（四）：MCP 协议实战：让 Claude Code 从代码编辑器升级为全栈开发代理的分水岭Claude Cod

新手上路（四）：MCP 实战——让 Claude Code 直连数据库、浏览器和外部 API

Windows 10/11 · Claude Code CLI v2.x · MCP Protocol 2026 · DeepSeek V4 Pro · 2026-05-01

一、这篇教程解决什么问题

一句话定位：前面所有教程都只让 Claude Code 操作本地文件和终端。这篇教你用 MCP（Model Context Protocol）把 Claude Code 连到真实外部系统——直接查数据库、操作 GitHub Issue、自动化浏览器测试、抓取网页内容。MCP 是 Claude Code 从"代码编辑器"升级为"全栈开发代理"的分水岭。

阅读前提：

已完成 Claude Code CLI 安装，claude --version 正常输出版本号
已完成《新手上路（二）》的初始化流水线，项目根目录存在 CLAUDE.md
了解 settings.json 的三层配置体系（《新手上路（三）》）
使用 Windows 10 或 Windows 11

读完能得到什么：

理解 MCP 协议的工作原理（stdio 管道通信、SSE 流、HTTP 三种传输方式）
掌握 claude mcp add / list / remove 全部命令和参数
8 个最实用 MCP 服务器的完整安装配置（filesystem / memory / git / github / postgres / puppeteer / fetch / brave-search）
用 TypeScript 从零写一个自定义 MCP 服务器
国内用户的完整排障方案（npx 镜像、Windows 路径、stdio 管道截断）
5 个真实 Debug 场景的五段式排错
一张 MCP 速查卡，后续配置任何 MCP 服务器都能对照执行

二、MCP 是什么——先搞懂原理再动手

2.1 一句话解释

MCP（Model Context Protocol）是 Anthropic 推出的开放标准协议，定义了 AI 助手（客户端）与外部工具（服务器）之间的通信方式。它让 Claude Code 能直接调用数据库查询、GitHub API、浏览器自动化等外部能力，而不需要你手动复制粘贴结果。

2.2 为什么不能直接用 Bash 管道代替

维度	直接用 Bash	用 MCP
安全性	Claude 能执行任意命令	MCP 服务器暴露固定工具列表，Claude 只能调用预定义的操作
类型安全	输出是原始文本，Claude 需要猜测格式	MCP 返回结构化 JSON，字段名和类型都有 schema 约束
权限控制	依赖 settings.json 的 Bash 权限白名单	MCP 服务器自带访问控制（如 filesystem 只能访问指定目录）
错误处理	命令失败只有 stderr 文本	MCP 有标准化的错误码和错误消息
可发现性	Claude 需要猜测系统上有什么工具	MCP 启动时自动列出所有可用工具及其参数说明

2.3 三种传输方式

MCP 定义了三种客户端-服务器通信方式：

传输方式	通信机制	适用场景	Claude Code 支持
stdio	标准输入/输出管道	本地进程，Claude Code 直接启动和管理服务器	✅ 默认
SSE	Server-Sent Events（HTTP 长连接）	远程服务器，服务器独立部署	✅ `--transport sse`
HTTP	HTTP 请求/响应	远程服务器，无状态调用	✅ `--transport http`

绝大多数本地 MCP 服务器使用 stdio 方式——Claude Code 启动一个子进程，通过 stdin/stdout 管道与它通信。这也是本篇教程的重点。

2.4 MCP 服务器内部结构

一个 MCP 服务器向 Claude 暴露三种能力：

MCP 服务器
├── Tools（工具）     ← Claude 可以调用的函数（如 "查询数据库"、"创建 Issue"）
├── Resources（资源） ← Claude 可以读取的数据（如 "文件内容"、"数据库 schema"）
└── Prompts（提示）   ← 预定义的提示模板（较少使用）

Claude Code 主要使用 Tools。当你配置好一个 MCP 服务器后，Claude 会自动发现该服务器提供的所有工具，并在需要时自动调用。

三、MCP 服务器管理命令

3.1 `claude mcp add` — 添加服务器

完整语法（来自 claude mcp add --help 实际输出）：

claude mcp add [options] <name> <commandOrUrl> [args...]

核心参数：

参数	说明	示例
`<name>`	服务器名称（自定义）	`filesystem`、`my-db`
`<commandOrUrl>`	启动命令或远程 URL	`npx`、`python`、`https://...`
`[args...]`	传给命令的参数	`-y`, `@modelcontextprotocol/server-filesystem`
`-s, --scope`	配置存储位置	`local`（默认）/ `user` / `project`
`-t, --transport`	传输方式	`stdio`（默认）/ `sse` / `http`
`-e, --env`	环境变量	`-e API_KEY=xxx`
`-H, --header`	HTTP 请求头（SSE/HTTP 传输）	`-H "Authorization: Bearer xxx"`

scope 说明：

scope	存储位置	作用范围	是否提交 Git
`local`	`项目/.mcp.json`	仅当前项目，仅你	不提交
`project`	`项目/.mcp.json`	当前项目，团队共享	提交
`user`	`~/.claude/settings.json`	所有项目	仅本地

3.2 `claude mcp list` — 查看已配置的服务器

claude mcp list

输出示例：

Checking MCP server health…

ho: python C:/Workspace/HandsOn/mcp-servers/handson-server/server.py - ✓ Connected

3.3 `claude mcp remove` — 删除服务器

claude mcp remove <name>

四、8 个最实用的 MCP 服务器实战

以下是 8 个经过验证的 MCP 服务器，按实用性排序。每个都给出完整的 Windows 安装命令。

Windows 关键注意事项：MCP 官方文档明确指出，在 Windows 上使用 npx 启动 MCP 服务器时，需要用 cmd /c 包裹，否则 stdio 管道会被 Windows 的命令解释器截断。本教程所有命令已做 Windows 适配。

4.1 Filesystem — 安全的文件系统访问

用途：让 Claude 在指定目录内安全地读写文件，不越界。

安装命令：

claude mcp add filesystem -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Workspace

alt text转存失败，建议直接上传图片文件

最后的 C:\Workspace 是允许访问的根目录。Claude 只能操作这个目录下的文件。你可以改成任何你需要的路径。

验证：

claude mcp list

预期输出中应包含 filesystem 且状态为 ✓ Connected。 alt text转存失败，建议直接上传图片文件

使用示例（在 Claude Code 会话中）：

你：列出 C:\Workspace 下所有 .py 文件
Claude：[自动调用 MCP filesystem 的 list_directory 工具]

安全说明：

只暴露需要的目录，不要设成 C:\
该服务器不提供删除操作（只读 + 写入 + 创建），安全性较高

4.2 Memory — 知识图谱持久化记忆

用途：给 Claude 一个跨会话的"记忆系统"，用知识图谱存储实体和关系，而不是纯文本文件。

安装命令：

claude mcp add memory -- cmd /c npx -y @modelcontextprotocol/server-memory

使用示例：

你：记住：这个项目使用 MongoDB，连接串在 .env 的 MONGODB_URI 字段
Claude：[调用 memory 的 create_entities 工具，写入知识图谱]

[下次新会话]
你：我们项目用什么数据库？
Claude：[调用 memory 的 search_nodes 工具] 你的项目使用 MongoDB...

与 CLAUDE.md 的区别：

维度	CLAUDE.md	MCP Memory
存储方式	纯文本 Markdown	结构化知识图谱（实体 + 关系）
检索方式	全文注入上下文	按关键词搜索，按需加载
适合存什么	项目规则、编码规范	事实、决策、跨项目知识
token 消耗	每次会话全量注入	仅搜索结果注入

4.3 Git — Git 仓库操作

用途：让 Claude 直接查看 git log、diff、blame，不需要跑 bash 命令。

安装命令（Python 实现，需要 uvx）：

# 先安装 uv（如果没有）
pip install uv

# 添加 MCP 服务器
claude mcp add git -- uvx mcp-server-git --repository C:\Workspace\你的项目

如果你没装 uv/uvx，也可以用 pip 安装：
pip install mcp-server-git
claude mcp add git -- python -m mcp_server_git --repository C:\Workspace\你的项目

提供的工具：

git_status — 查看工作区状态
git_diff_unstaged / git_diff_staged — 查看未暂存/已暂存的差异
git_log — 查看提交历史
git_show — 查看某个提交的详情
git_blame — 查看某行代码的最后修改者

4.4 GitHub — GitHub API 集成

用途：让 Claude 直接操作 GitHub Issue、PR、Review，不需要离开 Claude Code 去浏览器。

安装命令：

# 先生成 GitHub Personal Access Token
# 访问 https://github.com/settings/tokens → Generate new token (classic)
# 勾选 repo、read:org、read:user 权限

claude mcp add github -- cmd /c npx -y @modelcontextprotocol/server-github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxx你的Token

注意：GitHub MCP 服务器已从官方参考仓库归档（archived），但仍可正常使用。归档只是表示不再由 MCP 核心团队维护，功能不受影响。

提供的工具：

list_issues / get_issue / create_issue — Issue 管理
list_pull_requests / get_pull_request / create_pull_request — PR 管理
create_pull_request_review — PR 审查
search_repositories / list_commits — 仓库浏览
fork_repository / create_branch — 仓库操作

使用示例：

你：查看 affaan-m/everything-claude-code 仓库的最新 5 个 open issues
Claude：[调用 list_issues 工具] 以下是最新 5 个 open issues...

你：给 issue #123 添加评论 "这个 bug 已在 v2.1.98 修复"
Claude：[调用 add_issue_comment 工具] 已添加评论

4.5 PostgreSQL — 数据库直连查询

用途：让 Claude 直接查询 PostgreSQL 数据库，生成 SQL、查看 schema、分析数据。

安装命令：

claude mcp add postgres -- cmd /c npx -y @modelcontextprotocol/server-postgres postgresql://用户名:密码@localhost:5432/数据库名

连接串格式：

postgresql://用户名:密码@主机:端口/数据库名

示例：

claude mcp add postgres -- cmd /c npx -y @modelcontextprotocol/server-postgres postgresql://postgres:mypassword@localhost:5432/myapp

安全警告：该服务器是只读的（SELECT 语句），不能执行 INSERT/UPDATE/DELETE。这是设计如此，防止 Claude 误操作数据。如果需要写入能力，需要自己开发或使用社区 MCP 服务器。

使用示例：

你：查询 users 表的 schema 和最近 10 条记录
Claude：[调用 query 工具]
  → SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'users';
  → SELECT * FROM users ORDER BY created_at DESC LIMIT 10;

4.6 Puppeteer — 浏览器自动化

用途：让 Claude 控制 Chrome 浏览器，截图、点击、填表、自动化测试。

安装命令：

claude mcp add puppeteer -- cmd /c npx -y @modelcontextprotocol/server-puppeteer

首次运行会自动下载 Chromium（约 170MB），国内用户可能需要等待较长时间或使用镜像。

提供的工具：

puppeteer_navigate — 打开网页
puppeteer_screenshot — 截图
puppeteer_click — 点击元素
puppeteer_fill — 填写表单
puppeteer_evaluate — 执行 JavaScript

使用示例：

你：打开 http://localhost:3000，截图，然后点击登录按钮
Claude：[依次调用 navigate → screenshot → click]

4.7 Fetch — 网页内容抓取

用途：让 Claude 抓取任意网页内容，自动转换为 Markdown 格式。

安装命令：

claude mcp add fetch -- cmd /c npx -y @modelcontextprotocol/server-fetch

使用示例：

你：帮我看看这个 API 文档 https://api.example.com/docs 里有哪些端点
Claude：[调用 fetch 工具，获取网页并解析] 该 API 包含以下端点...

与内置 WebFetch 的区别：

维度	内置 WebFetch	MCP Fetch
需要配置	不需要	需要安装 MCP 服务器
输出格式	AI 处理后的摘要	原始 HTML → Markdown 转换
可定制性	低	可配置请求头、超时等

4.8 Brave Search — 实时网络搜索

用途：让 Claude 搜索互联网获取最新信息。需要科学上网，可用Kimi serach或者其他项目代替，也可以不装

安装命令：

# 先获取 Brave Search API Key（免费额度：每月 2000 次查询）
# 访问 https://brave.com/search/api/ 注册

claude mcp add brave-search -- cmd /c npx -y @modelcontextprotocol/server-brave-search -e BRAVE_API_KEY=BSA_xxxx你的Key

注意：Brave Search 服务器已从官方参考仓库归档，原包 @modelcontextprotocol/server-brave-search 可能不再更新。Brave 官方维护了新版本：@anthropic-ai/brave-search-mcp-server 或 brave/brave-search-mcp-server。如果原包安装失败，使用：
claude mcp add brave-search -- cmd /c npx -y @anthropic-ai/brave-search-mcp-server -e BRAVE_API_KEY=BSA_xxxx

五、MCP 配置文件详解

5.1 配置文件位置

当你运行 claude mcp add 时，配置会写入对应 scope 的文件：

scope	文件路径	格式
`local`（默认）	`项目/.mcp.json`	JSON
`project`	`项目/.mcp.json`	JSON
`user`	`~/.claude/settings.json` 中的 `mcpServers` 字段	JSON

5.2 `.mcp.json` 文件格式

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\Workspace"]
    },
    "memory": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"]
    },
    "postgres": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-postgres", "postgresql://postgres:password@localhost:5432/mydb"]
    },
    "github": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx你的Token"
      }
    }
  }
}

5.3 手动编辑 vs CLI 命令

# CLI 命令方式（推荐）
claude mcp add filesystem -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Workspace
claude mcp remove filesystem

# 手动编辑方式（批量配置时更方便）
# 直接编辑 项目/.mcp.json 文件

两种方式效果完全一致。CLI 命令会自动处理 JSON 格式，手动编辑时注意 JSON 语法（逗号、引号）。

六、自定义 MCP 服务器开发（TypeScript）---可选项

当现有 MCP 服务器不能满足需求时，你可以自己开发。

6.1 初始化项目

mkdir C:\Workspace\my-mcp-server
cd C:\Workspace\my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod

6.2 编写服务器代码

文件：C:\Workspace\my-mcp-server\server.ts

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-custom-server",
  version: "1.0.0",
});

// 定义一个工具：查询公司内部 Wiki
server.tool(
  "search_wiki",                          // 工具名称
  "搜索公司内部 Wiki 文档",                  // 工具描述（Claude 靠这个判断何时调用）
  {
    query: z.string().describe("搜索关键词"),
  },
  async ({ query }) => {
    // 这里替换为你的实际 Wiki API 调用
    const results = await fetch(`https://wiki.internal/api/search?q=${query}`);
    const data = await results.json();

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(data, null, 2),
        },
      ],
    };
  }
);

// 定义另一个工具：查询项目进度
server.tool(
  "get_project_status",
  "获取项目当前进度和待办事项",
  {
    project_id: z.string().describe("项目 ID"),
  },
  async ({ project_id }) => {
    // 实际实现
    return {
      content: [
        {
          type: "text",
          text: `项目 ${project_id} 当前进度：75%，待办事项 3 项`,
        },
      ],
    };
  }
);

// 启动服务器（stdio 传输）
const transport = new StdioServerTransport();
await server.connect(transport);

6.3 编译并注册

# 编译 TypeScript
npx tsc server.ts --outDir dist --module esnext --target es2022 --moduleResolution node

# 注册到 Claude Code
claude mcp add my-server -- node C:\Workspace\my-mcp-server\dist\server.js

6.4 验证

claude mcp list
# 应看到 my-server: node C:\Workspace\my-mcp-server\dist\server.js - ✓ Connected

在 Claude Code 会话中测试：

你：帮我搜索 Wiki 中关于 "API 设计规范" 的文档
Claude：[自动调用 search_wiki 工具] 找到以下相关文档...

七、MCP 生态资源

7.1 官方参考服务器（当前维护中）

服务器	npm 包	用途
Filesystem	`@modelcontextprotocol/server-filesystem` (v2026.1.14)	安全文件操作
Memory	`@modelcontextprotocol/server-memory` (v2026.1.26)	知识图谱记忆
Git	`mcp-server-git` (pip)	Git 仓库操作
Fetch	`@modelcontextprotocol/server-fetch`	网页抓取
Time	`@modelcontextprotocol/server-time`	时区转换
Sequential Thinking	`@modelcontextprotocol/server-sequentialthinking`	思维链推理
Everything	`@modelcontextprotocol/server-everything`	参考/测试服务器

7.2 已归档但仍在使用的服务器

以下服务器已从官方仓库归档到 servers-archived，但 npm 包仍可正常安装使用：

服务器	npm 包	用途	归档原因
GitHub	`@modelcontextprotocol/server-github`	GitHub API	功能稳定，不再积极开发
PostgreSQL	`@modelcontextprotocol/server-postgres` (v0.6.2)	数据库查询（只读）	同上
Puppeteer	`@modelcontextprotocol/server-puppeteer` (v2025.5.12)	浏览器自动化	同上
Brave Search	`@modelcontextprotocol/server-brave-search`	网络搜索	Brave 官方接管维护
Slack	`@modelcontextprotocol/server-slack`	Slack 消息	Zencoder 接管维护
SQLite	`@modelcontextprotocol/server-sqlite`	SQLite 数据库	同上
Redis	`@modelcontextprotocol/server-redis`	Redis 操作	同上
GitLab	`@modelcontextprotocol/server-gitlab`	GitLab API	同上

7.3 社区资源

MCP 官方注册表：registry.modelcontextprotocol.io — 搜索所有已发布的 MCP 服务器
MCP 规范官网：modelcontextprotocol.io — 协议文档和开发指南
MCP SDK：支持 10 种语言（TypeScript / Python / Go / Java / Kotlin / C# / Ruby / Rust / Swift / PHP）
社区精选列表：github.com/punkpeye/aw…

八、国内用户特别注意

8.1 npx 拉取 npm 包超时

npx -y @modelcontextprotocol/server-xxx 首次运行时需要从 npm 下载包。国内网络到 npmjs.org 的连接不稳定，经常超时。

解决方案：配置 npm 国内镜像源

# 使用淘宝 npmmirror 镜像
npm config set registry https://registry.npmmirror.com

# 验证
npm config get registry
# 应输出 https://registry.npmmirror.com

设置后所有 npx 命令都会从国内镜像下载，速度通常可达 MB/s 级别。

8.2 Puppeteer / Chromium 下载慢

Puppeteer 首次运行需要下载 Chromium（约 170MB），默认从 storage.googleapis.com 下载，在国内极慢。

解决方案：

# 使用淘宝 Chromium 镜像
$env:PUPPETEER_DOWNLOAD_BASE_URL = "https://cdn.npmmirror.com/binaries/chrome-for-testing"

# 永久写入
[System.Environment]::SetEnvironmentVariable("PUPPETEER_DOWNLOAD_BASE_URL", "https://cdn.npmmirror.com/binaries/chrome-for-testing", "User")

8.3 Windows 上 stdio 管道被 cmd.exe 截断

症状：MCP 服务器启动后立刻断开，claude mcp list 显示 ✗ Disconnected。

根因：在 Windows 上，如果 Claude Code 的 shell 环境是 cmd.exe，直接执行 npx 会导致 stdio 管道被 cmd.exe 的中间层截断。必须用 cmd /c 显式包裹，让 cmd.exe 作为父进程正确传递管道。

解决：所有 npx 命令统一使用 cmd /c npx ... 格式，本教程所有命令已做此适配。

8.4 GitHub Token 在国内的获取

如果无法访问 github.com/settings/tokens：

# 使用 gh CLI 生成 token（如果已安装 GitHub CLI）
gh auth login
gh auth token

或者使用 Gitee 等国内平台的 MCP 服务器替代 GitHub。

九、Debug #1 — MCP 服务器连接失败（stdio 管道截断）

报错日志

claude mcp list

Checking MCP server health…

filesystem: cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Workspace - ✗ Disconnected

或者在 Claude Code 会话中尝试使用 MCP 工具时：

Error: MCP server "filesystem" is not connected

根因

Windows 上 stdio 管道通信有两个常见的失败点：

cmd.exe 中间层截断：如果命令是 npx ...（没有 cmd /c 前缀），Windows 会通过 cmd.exe 间接执行 npx，cmd.exe 可能会错误地处理 stdin/stdout 管道的二进制数据流，导致 MCP 的 JSON-RPC 消息被截断。
npx 首次下载失败：npx -y @modelcontextprotocol/server-xxx 首次执行需要下载 npm 包。如果网络不通（国内直连 npmjs.org 超时），下载失败但不会报明显错误，服务器进程直接退出。

一览对比表

对比维度	修复前	修复后
命令格式	`npx -y @modelcontextprotocol/...`	`cmd /c npx -y @modelcontextprotocol/...`
npm 源	npmjs.org（国内慢）	registry.npmmirror.com（国内快）
服务器状态	`✗ Disconnected`	`✓ Connected`

代码修复

修复前（直接 npx，Windows 上会失败）：

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem C:\Workspace

修复后（用 cmd /c 包裹 + 配置镜像源）：

# 第 1 步：配置 npm 镜像源（如果还没配）
npm config set registry https://registry.npmmirror.com

# 第 2 步：删除旧配置
claude mcp remove filesystem

# 第 3 步：重新添加（用 cmd /c 包裹）
claude mcp add filesystem -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Workspace

验证

claude mcp list

预期输出：

Checking MCP server health…

filesystem: cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Workspace - ✓ Connected

十、Debug #2 — npx 拉取 MCP 包超时

报错日志

npm ERR! code ETIMEDOUT
npm ERR! errno -4039
npm ERR! network request to https://registry.npmjs.org/@modelcontextprotocol%2fserver-filesystem failed, reason:
npm ERR! network connect ETIMEDOUT 104.16.24.35:443

或者：

npm ERR! code ECONNRESET
npm ERR! network aborted

根因

npm 默认从 registry.npmjs.org 下载包，该域名的 CDN 节点在国内访问不稳定。DNS 解析到的 IP（如 104.16.24.35 是 Cloudflare 的 IP）在国内经常被 SNI 干扰或连接重置。首次运行 npx -y 时需要下载整个 npm 包（MCP 服务器通常 5-20MB），超时概率很高。

一览对比表

对比维度	修复前	修复后
npm registry	`registry.npmjs.org`	`registry.npmmirror.com`
下载速度	超时 / < 10 KB/s	通常 MB/s 级别
持久性	—	写入 `.npmrc`，永久生效

代码修复

# 设置国内镜像源（永久生效）
npm config set registry https://registry.npmmirror.com

# 清除可能损坏的缓存
npm cache clean --force

# 重新添加 MCP 服务器
claude mcp add filesystem -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Workspace

验证

# 测试 npm 下载速度
npm ping
# 应输出 npm notice PING https://registry.npmmirror.com

# 验证 MCP 服务器
claude mcp list
# filesystem 应为 ✓ Connected

十一、Debug #3 — MCP 工具在 Claude 中不显示

报错日志

claude mcp list 显示服务器已连接，但在 Claude Code 会话中 Claude 完全不知道这个 MCP 服务器提供的工具。你让它查询数据库，它说"我没有数据库访问能力"。

根因

MCP 服务器启动后需要完成"能力握手"（capability handshake）：服务器向客户端发送它支持的工具列表和参数 schema。如果握手过程中服务器的工具描述（description）为空或格式错误，Claude 会忽略这些工具。另一个常见原因是 MCP 服务器启动成功但监听的是错误的通信通道（比如服务器用了 SSE 但客户端配置的是 stdio）。

一览对比表

对比维度	修复前	修复后
服务器状态	✓ Connected	✓ Connected
工具可见性	Claude 不知道有工具	Claude 能看到并调用工具
根因	工具 description 为空 / 传输方式不匹配	补全 description / 统一传输方式

代码修复

检查 1：确认服务器确实提供了工具

# 在 Claude Code 会话中输入
/mcp

这会列出所有 MCP 服务器及其提供的工具。如果某个服务器显示 "0 tools"，说明服务器本身有问题。

检查 2：确认自定义服务器的工具 description 不为空

// ✗ 错误：description 为空
server.tool("search_wiki", "", { ... }, handler);

// ✓ 正确：description 清晰描述工具功能
server.tool("search_wiki", "搜索公司内部 Wiki 文档", { ... }, handler);

Claude 靠 description 判断何时调用工具。description 为空 = Claude 永远不会调用。

检查 3：重启 Claude Code 会话

MCP 服务器列表在会话启动时加载。如果在会话运行中添加了新 MCP 服务器，需要重启会话才能生效。

# 退出当前会话
/exit

# 重新启动
claude

验证

在 Claude Code 会话中：

你：你能使用哪些 MCP 工具？
Claude：我目前可以使用以下 MCP 工具：
  - filesystem: list_directory, read_file, write_file, ...
  - memory: create_entities, search_nodes, ...

十二、Debug #4 — MCP 服务器权限不足

报错日志

在 Claude Code 会话中使用 MCP 工具时：

Error: EACCES: permission denied, open 'C:\Windows\System32\config\system'

或者 PostgreSQL MCP 服务器：

Error: connection refused: FATAL: password authentication failed for user "readonly"

根因

MCP 服务器有两层权限控制：

MCP 服务器自身的访问控制：如 filesystem 服务器只能访问启动时指定的目录；postgres 服务器只能执行 SELECT（只读）。
底层资源的权限：如文件系统权限、数据库用户权限。MCP 服务器以启动它的用户身份运行，继承该用户的系统权限。

当 Claude 尝试访问 MCP 服务器允许范围之外的资源时，服务器会拒绝并返回错误。

一览对比表

对比维度	修复前	修复后
filesystem 根目录	`C:\`（过大，越权）	`C:\Workspace`（精确到项目目录）
postgres 用户	`root` / `postgres`（超级用户）	`readonly`（最小权限用户）
错误类型	EACCES / password authentication failed	正常执行

代码修复

Filesystem：缩小访问范围

# 删除旧配置
claude mcp remove filesystem

# 重新添加，只暴露项目目录
claude mcp add filesystem -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Workspace\你的项目

PostgreSQL：使用最小权限用户

-- 在 PostgreSQL 中创建只读用户（以超级用户身份执行）
CREATE USER claude_readonly WITH PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE myapp TO claude_readonly;
GRANT USAGE ON SCHEMA public TO claude_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO claude_readonly;

# 使用只读用户连接
claude mcp add postgres -- cmd /c npx -y @modelcontextprotocol/server-postgres postgresql://claude_readonly:secure_password@localhost:5432/myapp

验证

# 在 Claude Code 会话中测试边界
你：读取 C:\Windows\System32\config\system 文件
Claude：[调用 filesystem 工具] Error: Access denied - path is outside allowed directory

你：查询 users 表的前 5 条记录
Claude：[调用 postgres query 工具] 成功返回 5 条记录

你：删除 users 表
Claude：[调用 postgres query 工具] Error: permission denied（只读用户无法执行 DELETE）

十三、Debug #5 — MCP 服务器启动报错 "Cannot find module"

报错日志

Error: Cannot find module '@modelcontextprotocol/sdk'
Require stack:
- C:\Users\<用户名>\my-mcp-server\dist\server.js

或者：

Error: Cannot find module '@modelcontextprotocol/server-filesystem'

根因

两种情况：

自定义 MCP 服务器：开发时 npm install 安装了依赖，但编译后的 .js 文件引用的是 node_modules 的相对路径。如果把编译产物复制到其他目录运行，node_modules 不在旁边就会找不到模块。
npx 安装失败：npx -y 下载包的过程中断（网络超时），留下了不完整的 node_modules，后续运行报找不到模块。

一览对比表

对比维度	修复前	修复后
自定义服务器运行位置	随便复制到其他目录	在项目目录内运行（node_modules 就在旁边）
npx 下载	缓存损坏	清除缓存重新下载
模块解析	失败	成功

代码修复

情况 1：自定义服务器

# 确保在项目目录内运行
cd C:\Workspace\my-mcp-server

# 重新安装依赖
npm install

# 确认编译产物存在
ls dist/server.js

# 注册时使用完整绝对路径
claude mcp add my-server -- node C:\Workspace\my-mcp-server\dist\server.js

情况 2：npx 安装损坏

# 清除 npm 缓存
npm cache clean --force

# 清除 npx 缓存（Windows 路径）
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" -ErrorAction SilentlyContinue

# 重新添加 MCP 服务器
claude mcp remove filesystem
claude mcp add filesystem -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Workspace

验证

claude mcp list

预期输出：对应服务器显示 ✓ Connected。

十四、日常维护

14.1 查看 MCP 服务器状态

# 查看所有已配置的 MCP 服务器及其健康状态
claude mcp list

14.2 添加新 MCP 服务器的标准流程

# 第 1 步：确认镜像源
npm config get registry
# 应为 https://registry.npmmirror.com

# 第 2 步：添加服务器（Windows 必须用 cmd /c 包裹 npx）
claude mcp add <名称> -- cmd /c npx -y <npm包名> [参数]

# 第 3 步：验证
claude mcp list

# 第 4 步：在 Claude Code 会话中测试
# 重启会话后，让 Claude 调用新 MCP 工具

14.3 删除 MCP 服务器

claude mcp remove <名称>

14.4 更新 MCP 服务器版本

# npx -y 会自动使用最新版本（除非缓存了旧版本）
# 强制清除缓存获取最新版
npm cache clean --force
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" -ErrorAction SilentlyContinue

# 重启 Claude Code 会话

十五、速查卡

15.1 MCP 命令速查

命令	作用
`claude mcp add <名称> -- <命令> [参数]`	添加 MCP 服务器（stdio）
`claude mcp add -t http <名称> <URL>`	添加 HTTP 传输的远程服务器
`claude mcp add -t sse <名称> <URL>`	添加 SSE 传输的远程服务器
`claude mcp add -e KEY=val <名称> -- <命令>`	带环境变量添加
`claude mcp add -s user <名称> -- <命令>`	添加到用户级配置（所有项目）
`claude mcp add -s project <名称> -- <命令>`	添加到项目级配置（团队共享）
`claude mcp list`	查看所有已配置的 MCP 服务器
`claude mcp remove <名称>`	删除 MCP 服务器

15.2 MCP 服务器安装速查

服务器	Windows 安装命令
Filesystem	`claude mcp add filesystem -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Workspace`
Memory	`claude mcp add memory -- cmd /c npx -y @modelcontextprotocol/server-memory`
Git	`claude mcp add git -- uvx mcp-server-git --repository C:\Workspace\项目`
GitHub	`claude mcp add github -- cmd /c npx -y @modelcontextprotocol/server-github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx`
PostgreSQL	`claude mcp add postgres -- cmd /c npx -y @modelcontextprotocol/server-postgres postgresql://user:pass@host:5432/db`
Puppeteer	`claude mcp add puppeteer -- cmd /c npx -y @modelcontextprotocol/server-puppeteer`
Fetch	`claude mcp add fetch -- cmd /c npx -y @modelcontextprotocol/server-fetch`
Brave Search	`claude mcp add brave-search -- cmd /c npx -y @modelcontextprotocol/server-brave-search -e BRAVE_API_KEY=BSA_xxx`

15.3 配置文件位置速查

文件	路径	作用
项目 MCP 配置	`C:\Workspace\你的项目\.mcp.json`	项目级 MCP 服务器列表
用户 MCP 配置	`C:\Users\<用户名>\.claude\settings.json` 中 `mcpServers`	用户级 MCP 服务器列表
npm 全局配置	`C:\Users\<用户名>\.npmrc`	npm registry 镜像源

15.4 常见报错 → 解决方案映射表

报错特征	解决方案
`✗ Disconnected`	Windows 缺少 `cmd /c` 前缀 → Debug #1
`ETIMEDOUT` / `ECONNRESET` npm 下载	npm 镜像源未配置 → Debug #2
服务器连接但 Claude 不知道工具	工具 description 为空 / 未重启会话 → Debug #3
`EACCES` / `permission denied`	MCP 服务器访问范围过大 → Debug #4
`Cannot find module`	npx 缓存损坏 / 自定义服务器路径错误 → Debug #5
`MCP server is not connected`	服务器进程崩溃，检查 `claude mcp list` 状态
工具调用返回空结果	MCP 服务器内部错误，查看服务器日志

十六、参考文献

Model Context Protocol 官方文档 — MCP 协议规范、架构设计、SDK 文档的权威来源
MCP 官方参考服务器仓库 — 所有官方参考 MCP 服务器的源码和文档，含 Windows 配置说明
MCP 官方注册表 — 搜索所有已发布的 MCP 服务器
MCP TypeScript SDK — 自定义 MCP 服务器开发的 TypeScript SDK
MCP Python SDK — 自定义 MCP 服务器开发的 Python SDK
npmmirror 淘宝镜像 — 国内 npm 镜像源，解决 npx 下载超时问题
Puppeteer Chromium 镜像配置 — 配置 Puppeteer 使用国内 Chromium 镜像

新手上路（四）：MCP 协议实战：让 Claude Code 从代码编辑器升级为全栈开发代理的分水岭

新手上路（四）：MCP 实战——让 Claude Code 直连数据库、浏览器和外部 API

一、这篇教程解决什么问题

二、MCP 是什么——先搞懂原理再动手

2.1 一句话解释

2.2 为什么不能直接用 Bash 管道代替

2.3 三种传输方式

2.4 MCP 服务器内部结构

三、MCP 服务器管理命令

3.1 claude mcp add — 添加服务器

3.2 claude mcp list — 查看已配置的服务器

3.3 claude mcp remove — 删除服务器

四、8 个最实用的 MCP 服务器实战

4.1 Filesystem — 安全的文件系统访问

4.2 Memory — 知识图谱持久化记忆

4.3 Git — Git 仓库操作

4.4 GitHub — GitHub API 集成

4.5 PostgreSQL — 数据库直连查询

4.6 Puppeteer — 浏览器自动化

4.7 Fetch — 网页内容抓取

4.8 Brave Search — 实时网络搜索

五、MCP 配置文件详解

5.1 配置文件位置

5.2 .mcp.json 文件格式

5.3 手动编辑 vs CLI 命令

六、自定义 MCP 服务器开发（TypeScript）---可选项

6.1 初始化项目

6.2 编写服务器代码

6.3 编译并注册

6.4 验证

七、MCP 生态资源

7.1 官方参考服务器（当前维护中）

7.2 已归档但仍在使用的服务器

7.3 社区资源

八、国内用户特别注意

8.1 npx 拉取 npm 包超时

8.2 Puppeteer / Chromium 下载慢

8.3 Windows 上 stdio 管道被 cmd.exe 截断

8.4 GitHub Token 在国内的获取

九、Debug #1 — MCP 服务器连接失败（stdio 管道截断）

报错日志

根因

一览对比表

代码修复

验证

十、Debug #2 — npx 拉取 MCP 包超时

报错日志

根因

一览对比表

代码修复

验证

十一、Debug #3 — MCP 工具在 Claude 中不显示

报错日志

根因

一览对比表

代码修复

验证

十二、Debug #4 — MCP 服务器权限不足

报错日志

根因

一览对比表

代码修复

验证

十三、Debug #5 — MCP 服务器启动报错 "Cannot find module"

报错日志

根因

一览对比表

代码修复

验证

十四、日常维护

14.1 查看 MCP 服务器状态

14.2 添加新 MCP 服务器的标准流程

14.3 删除 MCP 服务器

14.4 更新 MCP 服务器版本

十五、速查卡

15.1 MCP 命令速查

15.2 MCP 服务器安装速查

15.3 配置文件位置速查

15.4 常见报错 → 解决方案映射表

十六、参考文献

3.1 `claude mcp add` — 添加服务器

3.2 `claude mcp list` — 查看已配置的服务器

3.3 `claude mcp remove` — 删除服务器

5.2 `.mcp.json` 文件格式