MCP 服务器：让 Claude Code 连接外部世界

Claude Code 本身能读写文件、运行命令、搜索代码。但如果你想让它搜网页、查数据库、调内部 API，就需要通过 MCP（Model Context Protocol）连接外部服务器。

简单理解：MCP 就是 Claude Code 的插件系统。每个 MCP server 提供一组工具，挂载后 Claude 就能直接使用这些工具。

快速上手：5 分钟配好第一个 MCP

以 Brave Search（网页搜索）为例：

第一步：获取 API Key 去 Brave Search API 注册，免费额度足够个人使用。

第二步：添加配置打开 Claude Code 的设置文件 ~/.claude/settings.json（如果没有就创建），添加：

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "你的API密钥"
      }
    }
  }
}

第三步：重启 Claude Code，试一下

搜索一下 "Claude Code 最新更新" 的网页结果

如果 Claude 能返回搜索结果，说明配置成功。

配置文件有两个位置：~/.claude/settings.json（全局）和项目根目录的 .claude/settings.json（项目级）。项目级配置优先于全局配置。

实用 MCP 服务器推荐

根据实际使用频率排序：

服务器	用途	适合场景
Brave Search	网页搜索	需要查最新信息、技术文档
GitHub	操作 GitHub API	管理 Issue、PR、仓库
SQLite / PostgreSQL	数据库查询	直接在对话中查数据
Filesystem	扩展文件访问	读取项目外的文件

不建议一次挂载太多。根据 Anthropic 的研究，工具总数超过 10-15 个后 AI 的选择准确率会下降。先配你最常用的 2-3 个就够了。

配置方式详解

全局配置（所有项目共享）

// ~/.claude/settings.json
{
  "mcpServers": {
    "server-name": {
      "command": "命令",
      "args": ["参数列表"],
      "env": {
        "环境变量": "值"
      }
    }
  }
}

项目级配置（仅当前项目生效）

// .claude/settings.json（项目根目录）
{
  "mcpServers": {
    "project-db": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-sqlite", "--db", "./data/app.db"]
    }
  }
}

项目级适合放数据库连接、项目专用工具这类和项目绑定的配置。

配置字段说明

command：启动 MCP server 的命令（通常是 npx、node 或 python）
args：命令参数
env：传给 server 进程的环境变量（放 API Key 等敏感信息）

要不要自己写 MCP Server

大部分场景不需要。先按这个顺序判断：

官方 server 能不能满足？ → Anthropic 提供了 Brave Search、GitHub、文件系统等常用 server
社区 server 有没有？ → MCP Server 目录有大量社区贡献
都不行才自建 → 通常是需要对接内部 API、私有知识库或企业专属工具链时

如果确定要自建，参考 → 自定义 MCP 服务器开发

常见配置问题

”MCP server failed to start”

最常见的原因：

npx 命令没装或版本太旧（需要 Node.js 18+）
API Key 没设或设错了
网络问题导致包下载失败

排查步骤：在终端手动运行 MCP server 的命令看报什么错：

BRAVE_API_KEY=xxx npx -y @anthropic-ai/mcp-server-brave-search

Claude 不使用 MCP 工具

配置了但 Claude 不调用 MCP 工具，通常是因为：

重启 Claude Code 后配置才生效
MCP server 提供的工具名称和你的描述不匹配，Claude 没意识到该用
明确告诉 Claude 使用哪个工具：「用 Brave Search 搜索 xxx」

API Key 安全

⚠️

不要把 API Key 直接写在项目级配置里并提交到 git。用环境变量引用：先设系统环境变量，再在配置中用 $ENV_NAME 引用。或者只在全局配置中放 Key。

MCP 的工作原理（了解即可）

MCP 基于 JSON-RPC 协议，采用客户端-服务器架构：

Claude Code（客户端）  ←→  MCP Server（服务端）
     ↓ 发起工具调用          ↓ 执行并返回结果
     ↓ 管理权限和会话        ↓ 维护资源状态

传输方式支持 stdio（本地进程，最常用）、HTTP 和 WebSocket。大多数场景用 stdio 就够了——Claude Code 会启动一个本地进程来运行 MCP server，通过标准输入输出通信。