Claude Code MCP 服务器配置实战指南

从零开始配置 Exa、Context7、Playwright、MarkItDown 四个 MCP 服务器

前言

MCP (Model Context Protocol) 是 Anthropic 推出的模型上下文协议，让 Claude Code 能够连接外部工具和服务。本文记录了我在 Claude Code 中配置 4 个实用 MCP 服务器的完整过程，包括踩坑和解决方案。

目标 MCP 服务器

MCP Server	功能	用途
Exa	AI 搜索引擎	高质量网页搜索、代码示例查找
Context7	实时文档	获取最新的库/框架文档
Playwright	浏览器自动化	E2E 测试、网页抓取、截图
MarkItDown	文档转换	将 PDF、Word、Excel 等转换为 Markdown

一、Exa MCP 配置（HTTP 模式）

Exa 提供了 HTTP 端点，配置最简单：

claude mcp add --transport http exa https://mcp.exa.ai/mcp

优点：无需安装 npm 包，直接通过 HTTP 连接，响应速度快。

二、Context7 MCP 配置

Context7 是 Upstash 开发的实时文档搜索工具，可以获取最新版本的库文档。

查找正确的包名

# 错误的包名（不存在）
npx @anthropic-ai/mcp-server-context7  # ❌

# 正确的包名
npx @upstash/context7-mcp  # ✅

安装命令

# 全局安装（推荐，避免每次 npx 下载）
npm install -g @upstash/context7-mcp

# 添加到 Claude Code
claude mcp add context7 -- npx -y @upstash/context7-mcp

三、Playwright MCP 配置

Playwright MCP 是微软官方的浏览器自动化服务器。

安装步骤

# 1. 安装 npm 包
npm install -g @playwright/mcp

# 2. 安装 Chromium 浏览器（必需）
npm install -g @playwright/test
npx playwright install chromium

# 3. 添加到 Claude Code
claude mcp add playwright -- npx -y @playwright/mcp

踩坑记录

问题：首次运行时显示 Failed to connect

原因：Playwright MCP 需要浏览器才能工作，默认不安装浏览器

解决：执行 npx playwright install chromium

可用工具

安装成功后，Playwright MCP 提供以下工具：

工具	功能
browser_navigate	导航到 URL
browser_click	点击元素
browser_snapshot	获取页面快照
browser_take_screenshot	截图
browser_type	输入文本
browser_evaluate	执行 JavaScript

四、MarkItDown MCP 配置

MarkItDown 是微软开发的文档转换工具，支持 29+ 种文件格式。

选择正确的实现

我最初尝试了 markdownify-mcp，但发现：

• 需要本地构建
• Windows 兼容性问题
• 配置复杂

最终选择了微软官方的 markitdown-mcp-npx，这是一个 NPX 包装器，自动处理 Python 环境。

安装步骤

# 添加到 Claude Code
claude mcp add markitdown -- npx -y markitdown-mcp-npx

首次运行

首次运行时，NPX 包装器会自动：

1. 检测 Python 3.10+ 环境
2. 创建虚拟环境
3. 安装 markitdown-mcp 及所有依赖

这个过程可能需要 2-3 分钟，请耐心等待。

权限问题解决

问题：Permission denied: '...\venv\Scripts\python.exe'

解决：删除临时目录重新安装

# Windows
rmdir /s /q "%TEMP%\markitdown-mcp-npx"

# 重新运行
npx -y markitdown-mcp-npx

支持的文件格式

类别	格式
文档	PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx)
图片	JPG, PNG, GIF（含 OCR）
音频	MP3, WAV（含转录，需 FFmpeg）
网页	HTTP/HTTPS URLs, YouTube
数据	CSV, JSON, XML
其他	ZIP, EPub

五、配置作用域：全局 vs 项目级

这是很多人容易踩坑的地方！Claude Code 的 MCP 配置有多个层级：

配置层级说明

配置文件	路径	作用范围	特点
mcp.json	C:\Users\{用户名}\.claude\mcp.json	所有项目	切换 Windows 用户会失效
.mcp.json	项目根目录	当前项目	跟着项目走，换机器也有效
claude.json	C:\Users\{用户名}\.claude.json	用户级别	存储在每个项目配置中

推荐配置方式

使用 --scope user 确保在任何目录下都能使用：

# 添加到用户级别（推荐）
claude mcp add context7 --scope user -- npx -y @upstash/context7-mcp
claude mcp add playwright --scope user -- npx -y @playwright/mcp
claude mcp add markitdown --scope user -- npx -y markitdown-mcp-npx
claude mcp add --transport http exa --scope user -- https://mcp.exa.ai/mcp

踩坑记录

问题：在 C:\Users\{用户名} 目录下运行 claude mcp list，某些 MCP 不显示

原因：每个目录都有独立的项目配置，可能没有继承全局配置

解决：使用 --scope user 显式添加到用户配置中

查看当前配置

# 查看用户级别配置文件
cat C:\Users\86177\.claude.json | grep -A 20 '"mcpServers"'

mcp.json 文件示例

手动编辑 C:\Users\{用户名}\.claude\mcp.json：

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    },
    "markitdown": {
      "command": "npx",
      "args": ["-y", "markitdown-mcp-npx"]
    }
  }
}

六、验证配置

claude mcp list

预期输出：

Checking MCP server health...

plugin:episodic-memory:episodic-memory - ✓ Connected
markitdown: npx -y markitdown-mcp-npx - ✓ Connected
context7: npx -y @upstash/context7-mcp - ✓ Connected
playwright: npx -y @playwright/mcp - ✓ Connected
exa: https://mcp.exa.ai/mcp (HTTP) - ✓ Connected

七、常见问题排查

1. MCP 服务器显示 “Failed to connect”

可能原因：

• npm 包未安装或未下载完成
• Python 环境缺失（MarkItDown）
• 浏览器未安装（Playwright）

排查步骤：

# 1. 手动测试 MCP 服务器
npx @upstash/context7-mcp  # 应该启动无报错

# 2. 检查 Python 版本
python --version  # 需要 3.10+

# 3. 检查 Playwright 浏览器
npx playwright install chromium

2. npx 每次都重新下载

原因：npx 默认会检查最新版本

解决：全局安装

npm install -g @upstash/context7-mcp

然后修改配置使用全局命令。

3. MCP 工具不显示

MCP 工具需要首次调用才会加载到工具列表。可以运行：

/mcp

查看可用的 MCP 工具。

八、最佳实践

1. 使用 -y 标志

在非交互环境（如 Claude Desktop 配置）中，必须使用 -y 标志避免 npx 安装提示：

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

2. HTTP vs STDIO

模式	适用场景	优点	缺点
HTTP	远程服务、需要持久化	快速、无需本地安装	需要 API Key
STDIO	本地工具	完全本地、安全	首次启动慢

3. 包名对照表

很多 MCP 服务器有不同的包名，容易混淆：

MCP	官方包名	错误包名
Context7	@upstash/context7-mcp	@anthropic-ai/mcp-server-context7
Playwright	@playwright/mcp	@anthropic-ai/mcp-server-playwright
MarkItDown	markitdown-mcp-npx	markdownify-mcp

九、使用示例

Exa 搜索

搜索最新的 React 19 特性介绍

Claude 会使用 web_search_exa 工具搜索。

Context7 文档查询

帮我查 Next.js 15 的 App Router 最新 API

Playwright 自动化

打开 https://example.com 并截图

MarkItDown 转换

把这个 PDF 文件转换成 Markdown

总结

配置 MCP 服务器的关键步骤：

1. 找到正确的包名 - 这是最大的坑，很多教程使用过时的包名
2. 安装依赖 - Python 环境、浏览器等
3. 耐心等待首次启动 - npx 需要下载，Python 需要创建虚拟环境
4. 验证连接 - 使用 claude mcp list 检查状态

希望这篇博客能帮助你顺利配置 MCP 服务器，让 Claude Code 更加强大！

---

相关链接：

• Exa MCP
• Context7 GitHub
• Playwright MCP
• MarkItDown MCP
• MCP 官方文档