Claude Code MCP 服务器入门：从零到一接入工具调用

MCP（Model Context Protocol）是 Anthropic 在 2024 年底推出的开源协议，本质是给 LLM 装一根统一的工具调用插槽。Claude Code 是首批原生支持 MCP 的客户端之一——配置正确后，你可以让模型直接读写文件、查数据库、调 API、操作浏览器，再也不用一行行复制粘贴。

这篇是从零开始的实操指南。如果你只想 30 秒接入，跳到下面「最快路径」。如果你想搞懂为什么、避免所有坑，从头读。

拼车前置：MCP 调用要消耗 token（每次工具调用都会把结果回灌到上下文）。OpenClaw Carpool 一行接通 Max 20× 配额，避免被 rate limit 打断：
curl -fsSL https://cp.bizq.net/setup.sh | bash -s -- claude-max-20x

MCP 到底是什么

把 MCP 想成 LLM 的 USB 接口：

服务器（Server） = 工具提供方，比如 filesystem MCP server 提供读/写/列文件
客户端（Client） = LLM 宿主，比如 Claude Code、OpenClaw、Cursor
协议（Protocol） = JSON-RPC over stdio / HTTP / SSE，标准化的调用约定

好处是一次写、处处用：你写一个 MCP server，Claude Code、OpenClaw、Cursor、Continue 全都能直接装。

Claude Code 通过 MCP 能做什么：

直接访问本地文件系统（不用复制粘贴）
调 GitHub、Slack、Notion、Linear 等 API
查 PostgreSQL / SQLite / MySQL
控制 Playwright / Puppeteer / Chrome DevTools
跑 shell、连 ssh、操作 Docker

最快路径（30 秒）

打开终端，三行：

# 添加最常用的 filesystem 服务器
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Desktop
 
# 验证
claude mcp list
 
# 在 Claude Code 里输入 /mcp 查看连接状态

完了。下次 Claude Code 启动它就会自动拉起这个 MCP server。

三种添加方式（按你的习惯选）

方式一：CLI 命令（推荐新手）

# 基本语法
claude mcp add <名称> <命令> [参数...]
 
# 添加文件系统
claude mcp add my-fs -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
 
# 带环境变量
claude mcp add api-tool -e API_KEY=sk-xxxx -- /path/to/server-binary

-- 是分隔符，左边是 MCP 配置参数，右边是真正运行的命令。

方式二：直接编辑配置文件（推荐熟手）

CLI 向导每次输错都得重来，老手直接改文件更快。

配置文件位置：

平台	路径
macOS / Linux	`~/.claude.json`
Windows	`%USERPROFILE%\.claude.json`

打开后找到 / 新建 mcpServers 字段：

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"],
      "env": {}
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

改完重启 Claude Code 生效。

方式三：项目级 `.mcp.json`（团队共享）

让队友 clone 项目就自动得到一致的工具集：

claude mcp add shared-tools -s project -- npx -y @your-team/internal-mcp

这会在项目根写出 .mcp.json，提交到 git 即可。

{
  "mcpServers": {
    "shared-tools": {
      "command": "npx",
      "args": ["-y", "@your-team/internal-mcp"],
      "env": {}
    }
  }
}

作用域：弄清楚就不会迷路

MCP 配置有三层作用域，搞混了会出现「明明加了找不到」的灵异现象。

作用域	范围	标志	存储位置	适合
Local	当前目录下生效	默认	`~/.claude.json` 的 `projects` 段	单项目专用工具
User	所有项目共用	`-s user`	`~/.claude.json` 顶层 `mcpServers`	个人通用工具（fs、git）
Project	跟项目走、可入库	`-s project`	`<项目根>/.mcp.json`	团队协作

实务建议：filesystem、git、memory 这类用 -s user；项目特定的 schema、内部 API 用 -s project。

OpenClaw 原生 MCP 集成

OpenClaw 把 MCP 直接写进了 agent 配置——同一个 server 实例可被 Claude Code 和 OpenClaw agents 共享，不用配两次。

// ~/.openclaw/openclaw.json
{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/Documents"]
      },
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" }
      }
    }
  },
  "agents": {
    "*": { "mcp": ["filesystem", "github"] }
  }
}

跑：

openclaw mcp list                # 查看所有已注册的 MCP
openclaw mcp inspect filesystem  # 看具体 server 的工具清单
openclaw mcp test github -- list_repositories

openclaw mcp test 这条命令是我自己写得最多的——能在不进入对话的情况下验证 server 是否健康，比 Claude Code 的 /mcp 命令更精确。

10 个最值得装的 MCP 服务器

# 1. 文件系统
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects
 
# 2. GitHub
claude mcp add github -s user -e GITHUB_TOKEN=ghp_xxx -- npx -y @modelcontextprotocol/server-github
 
# 3. 浏览器自动化（Puppeteer）
claude mcp add puppeteer -s user -- npx -y @modelcontextprotocol/server-puppeteer
 
# 4. PostgreSQL
claude mcp add postgres -s user -e DATABASE_URL=postgresql://... -- npx -y @modelcontextprotocol/server-postgres
 
# 5. HTTP fetch
claude mcp add fetch -s user -- uvx mcp-server-fetch
 
# 6. Brave 搜索
claude mcp add search -s user -e BRAVE_API_KEY=xxx -- npx -y @modelcontextprotocol/server-brave-search
 
# 7. Slack
claude mcp add slack -s user -e SLACK_TOKEN=xoxb-xxx -- npx -y @modelcontextprotocol/server-slack
 
# 8. 时间/时区
claude mcp add time -s user -- npx -y @modelcontextprotocol/server-time
 
# 9. 跨会话记忆
claude mcp add memory -s user -- npx -y @modelcontextprotocol/server-memory
 
# 10. Sequential thinking（让模型分步推理）
claude mcp add thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinking

每个 server 都有自己的工具清单，装完后让 Claude 请列出可用工具，它会回答得很具体。

常见错误手册

错误 1：工具名校验失败

API Error 400: tools.11.custom.name: String should match pattern '^[a-zA-Z0-9_-]{1,64}$'

只能用字母、数字、下划线、短横线，不超过 64 字符。中文、空格、点号都会挂。

错误 2：找不到 server

MCP server 'my-server' not found

按顺序自查：

claude mcp list 看名字是否拼对
你当前所在目录是不是当初 add 时的目录（local 作用域受目录约束）
重启 Claude Code

错误 3：协议版本错误

"protocolVersion": "Required"

通常是 server 实现太旧。升级 Claude Code，再升级 server 包：

npm i -g @modelcontextprotocol/server-filesystem@latest

错误 4：Windows 路径反斜杠

Windows 路径在 CLI 里要么用正斜杠，要么用双反斜杠：

# 错的
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\Users\you\Documents
 
# 对的
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:/Users/you/Documents

错误 5：权限拒绝

Permission denied 多半是把 server 装在了系统路径需要 root。最简单的解法是把它装在用户目录、用 npx -y 临时拉取，不要 sudo。

调试技巧

启用调试日志

claude --mcp-debug

启动后所有 MCP 通信都打到 stderr，能看到完整的 JSON-RPC 交互。

在 Claude Code 内查状态

直接输入：

/mcp

会列出所有 server 的连接状态、工具数量。

查日志文件

macOS / Linux：

tail -f ~/Library/Logs/Claude/mcp*.log

Windows：

type "%APPDATA%\Claude\logs\mcp*.log"

手动起一遍 server

最有效的调试——直接跑 server 进程，看它有没有正常输出 stdio：

npx -y @modelcontextprotocol/server-filesystem ~/Documents

如果报错或一直卡住，那 server 本身就有问题，跟 Claude Code 没关系。

中国大陆环境注意点

路径中不要带中文

# 容易翻车
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ~/文档
 
# 稳
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

npm 镜像加速

# 临时
claude mcp add fs -- npx -y --registry=https://registry.npmmirror.com @modelcontextprotocol/server-filesystem ~/Documents
 
# 永久
npm config set registry https://registry.npmmirror.com

代理

如果你需要走 HTTP 代理：

npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890

写一个自己的 MCP server

现成的不够用？写一个其实很简单：

// my-mcp-server.mjs
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
const server = new Server(
  { name: 'my-custom-server', version: '1.0.0' },
  { capabilities: { tools: {} } }
);
 
server.setRequestHandler('tools/list', async () => ({
  tools: [{
    name: 'hello',
    description: '打招呼',
    inputSchema: {
      type: 'object',
      properties: { name: { type: 'string' } }
    }
  }]
}));
 
server.setRequestHandler('tools/call', async (req) => {
  if (req.params.name === 'hello') {
    return { content: [{ type: 'text', text: `Hello, ${req.params.arguments.name}` }] };
  }
});
 
await server.connect(new StdioServerTransport());

然后注册：

claude mcp add my-server -- node /path/to/my-mcp-server.mjs

工具的复杂度由你决定——我们 OpenClaw 的内部 ops MCP 里塞了 30+ 个工具，从查 Inngest 状态到回滚部署都能让 Claude 直接调用。

最佳实践清单

按需添加，不要一次塞 20 个 MCP——每个 server 都吃内存、占启动时间
定期 claude mcp remove 清掉不用的
只装可信来源的 server（github.com/modelcontextprotocol 官方组织 + 你审过代码的）
配置文件提交前过滤敏感 env（.gitignore 加上 .claude.json）
团队共享走 .mcp.json，个人偏好走 ~/.claude.json

立即开始

curl -fsSL https://cp.bizq.net/setup.sh | bash -s -- claude-max-20x
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

两条命令——拼车 + 第一个 MCP——你的 Claude Code 已经从聊天工具变成会动手的开发伙伴。

热门 MCP 服务器汇总 — 配套的精选 MCP 服务器目录
Claude Code 提示词指南 — 工具有了之后怎么写 prompt 让它会用
OpenClaw Claude Code 拼车配置指南 — 让 MCP 调用不被 rate limit 卡死

Claude Code 提示词指南：从工程实战中提炼的可复用模板热门 MCP 服务器汇总：Claude Code 用户实测的精选清单