Claude-Code配置Serper-MCP指南

文章目录

• [Claude Code 配置 Serper MCP 服务器完整指南](#Claude Code 配置 Serper MCP 服务器完整指南)
• • [一、背景：为什么需要 Serper MCP？](#一、背景：为什么需要 Serper MCP？)
  • 二、前置准备
  • • [1. 获取 Serper API Key](#1. 获取 Serper API Key)
    • [2. 环境要求](#2. 环境要求)
  • 三、核心配置步骤
  • • [步骤 1：创建 `.mcp.json` 配置文件](#步骤 1：创建 .mcp.json 配置文件)
    • [步骤 2：启用 MCP 服务器](#步骤 2：启用 MCP 服务器)
    • [步骤 3：验证配置](#步骤 3：验证配置)
  • 四、配置文件位置详解
  • [五、Serper MCP 提供的工具](#五、Serper MCP 提供的工具)
  • • [工具 1：`google_search`](#工具 1：google_search)
    • [工具 2：`scrape`](#工具 2：scrape)
  • 六、常见问题排查
  • • [问题 1：MCP 服务器未加载](#问题 1：MCP 服务器未加载)
    • [问题 2：API Key 无效](#问题 2：API Key 无效)
    • [问题 3：npx 下载失败](#问题 3：npx 下载失败)
    • [问题 4：Node.js 版本过低](#问题 4：Node.js 版本过低)
  • 七、配置摘要

Claude Code 配置 Serper MCP 服务器完整指南

说明：本文基于实际配置经验总结，环境：Linux, Node.js v24, Claude Code v2.1.92，让 Claude Code 拥有实时联网搜索和网页抓取能力。

一、背景：为什么需要 Serper MCP？

Claude Code 默认只能访问训练数据中的知识，无法进行实时网络搜索。通过配置 Serper MCP Server，可以让 Claude Code 获得两项强大的新能力：

• google_search：执行高级 Google 搜索（支持站点限定、文件类型、时间范围等操作符）
• scrape：抓取指定网页内容，提取纯文本和 Markdown 格式

这意味着你可以直接让 Claude Code 搜索最新的技术文档、查找论文、检索 GitHub 仓库等。

二、前置准备

1. 获取 Serper API Key

• Serper 是 Google Search API 的代理服务，提供免费额度（通常 2500 次免费搜索）。
  Serper 免费版的限制主要有：

1. 总量限制（最核心的限制）：免费额度是 2,500 次搜索，且是一次性的，不是按月重置，用完即止，需要付费购买更多 credits（$50/50,000 credits）。
2. 并发/速率限制

• Serper 官方并未公开说明免费版的具体 QPS 限制
• 付费版（Ultimate credits）默认速率限制是 300 queries/second
• 有用户反馈免费版的限制是：请求过于频繁会被限流（throttling），但没有明确的数字
• 对于 Claude Code MCP 场景，搜索是按需串行的，不太可能触达并发上限

3. 实际使用感受：用 Claude Code + Serper MCP 的场景下，每次搜索消耗 1 个 credit。2,500 次免费额度对日常使用来说够用一阵子，但如果频繁让 AI 自动搜索，消耗会比较快。

• 总结：免费版没有明确的并发数限制文档，主要限制就是 2,500 次的总量。正常通过 Claude Code 使用不会遇到并发问题。

---

1. 访问 https://serper.dev
2. 注册账号（支持 Google/GitHub 快捷登录）
3. 登录后进入 Dashboard → API Key 页面
4. 复制你的 API Key

注意：API Key 是敏感信息，不要提交到公开的代码仓库中。

2. 环境要求

• Node.js >= 18（推荐 v20+）
• npm（随 Node.js 安装）
• Claude Code CLI （@anthropic-ai/claude-code）

验证环境：

node -v   # 应输出 v18 或更高版本
npx --version
claude --version

三、核心配置步骤

步骤 1：创建 .mcp.json 配置文件

• Claude Code 使用 .mcp.json 文件来定义 MCP 服务器的连接方式。该文件位于 ~/.mcp.json （home 目录下，与 .claude/ 同级）。

# 创建或编辑配置文件
vim ~/.mcp.json

写入以下 JSON 内容：

{
  "serper": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/claude-code-mcp-serper"],
    "env": {
      "SERPER_API_KEY": "这里替换为你的真实API_KEY"
    }
  }
}

字段说明：

字段	说明
serper	服务器名称标识符，可自定义，但建议保持简洁
command	启动命令，使用 npx 直接运行，无需预先安装
args	命令行参数，-y 表示自动确认安装，后面跟包名
env	环境变量，SERPER_API_KEY 是 Serper 服务必需的认证信息

关键点 ：这里使用了 npx 方式，不需要提前 npm install -g 安装包。首次调用时 npx 会自动下载并缓存。

步骤 2：启用 MCP 服务器

在 ~/.claude/settings.local.json 中启用该服务器：

{
  "enabledMcpjsonServers": ["serper"],
  "enableAllProjectMcpServers": true
}

字段说明：

字段	说明
enabledMcpjsonServers	数组，列出要启用的 .mcp.json 中定义的服务器名称
enableAllProjectMcpServers	是否自动启用所有项目级别的 MCP 服务器

关键点 ：enabledMcpjsonServers 中的名称必须与 .mcp.json 中定义的键名完全一致。如果 .mcp.json 中的键名是 "serper"，这里也必须写 "serper"。

步骤 3：验证配置

重启 Claude Code 后，MCP 服务器会自动加载。你可以通过以下方式验证：

1. 直接提问测试：

   请搜索 2025 年最新的 React 新特性

2. Claude Code 会自动识别需要使用搜索能力，调用 google_search 工具

3. 如果配置正确，你会看到类似如下的工具调用信息：

   🛠️ Using tool: google_search
   {
     "q": "2025 React new features"
   }

---

四、配置文件位置详解

Claude Code 的 MCP 配置涉及两个文件，它们的关系如下：

~/
├── .mcp.json              ← 定义 MCP 服务器（名称、命令、参数、环境变量）
├── .claude/
│   └── settings.local.json    ← 启用哪些已定义的 MCP 服务器
└── settings.json          ← 通用设置（模型、API 地址等）

加载流程：

1. Claude Code 启动
2. 读取 .mcp.json 获取服务器定义列表
3. 读取 settings.local.json 的 enabledMcpjsonServers
4. 对匹配名称的服务器执行 command + args 启动
5. 将 env 中的环境变量注入子进程
6. 通过 stdio 协议与 MCP 服务器通信

五、Serper MCP 提供的工具

工具 1：google_search

执行 Google 搜索，支持丰富的操作符。

基本搜索：

搜索 "Python asyncio 教程"

高级搜索示例：

需求	查询示例
精确匹配	"exact phrase"
限定域名	site:github.com react hooks
排除词	python tutorial -youtube -video
文件类型	filetype:pdf deep learning
时间过滤	after:2024-01-01 machine learning news
标题搜索	intitle:review transformers
组合搜索	site:stackoverflow.com "TypeError" pandas

搜索 LinkedIn 人员：

site:linkedin.com/in/ "data scientist" Python "San Francisco"

搜索学术论文：

site:arxiv.org "transformer architecture" after:2024-01-01

工具 2：scrape

抓取指定 URL 的网页内容。

• 返回纯文本和可选的 Markdown 内容
• 自动提取 JSON-LD 和 head 元数据
• 保留文档结构

---

六、常见问题排查

问题 1：MCP 服务器未加载

症状：Claude Code 启动后没有显示 Serper 工具。

排查步骤：

1. 检查 .mcp.json 语法是否正确：

   cat ~/.mcp.json | python3 -m json.tool

2. 检查 settings.local.json 中的名称是否匹配：

   cat ~/.claude/settings.local.json

3. 重启 Claude Code

问题 2：API Key 无效

症状：搜索返回错误，提示认证失败。

解决方案：

1. 登录 serper.dev 确认 API Key 有效
2. 确认 .mcp.json 中 env 字段的 key 名称为 SERPER_API_KEY（全大写，不能拼错）
3. 检查 Key 前后是否有空格或换行符

问题 3：npx 下载失败

症状：网络问题导致 npx 无法下载包。

解决方案：

1. 使用国内 npm 镜像：

   export npm_config_registry=https://registry.npmmirror.com

2. 或者预先全局安装：

   npm install -g @anthropic-ai/claude-code-mcp-serper

   然后将 .mcp.json 中的 command 改为：

   {
     "serper": {
       "command": "@anthropic-ai/claude-code-mcp-serper",
       "env": {
         "SERPER_API_KEY": "your_key_here"
       }
     }
   }

问题 4：Node.js 版本过低

症状 ：报错提示 SyntaxError 或模块不兼容。

解决方案：

# 使用 nvm 升级 Node.js
nvm install 22
nvm use 22

---

七、配置摘要

最终的完整配置状态：

~/.mcp.json

{
  "serper": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/claude-code-mcp-serper"],
    "env": {
      "SERPER_API_KEY": "your_api_key_here"
    }
  }
}

~/.claude/settings.local.json

{
  "enabledMcpjsonServers": ["serper"],
  "enableAllProjectMcpServers": true
}

配置完成后，Claude Code 即可实时搜索互联网内容，极大扩展了其知识获取能力。