MCP Server

把 Claude Code 接到你自己的数据源和工具上。

MCP 是什么

MCP 全称 Model Context Protocol，是 Anthropic 在 2024 年 11 月正式推出的开放协议，专门用来解决一个老大难问题：LLM 怎么和外部工具、外部数据源打交道。协议本身开源，规范放在 GitHub 上，任何人都能实现自己的 client 或 server。

在 MCP 出现以前，每家 LLM 厂商都有自己的一套 function calling 格式，每接一个新工具都要写一份适配代码。MCP 的思路是把这一层标准化：工具方按协议实现一个 server，客户端（Claude Code、Claude Desktop、其他 IDE）按协议实现 client，中间不管接谁都用同一套消息。

对 Claude Code 用户来说，MCP 最直接的好处是：你可以让 Claude 去读私有数据库、调公司内部 API、看飞书文档，而不用自己写一坨 shell 脚本让它 curl 来 curl 去。协议本身开源、跨厂商，写好的 server 装到 Claude Desktop、Cursor、其他兼容客户端上也照跑。

从架构上看 MCP 分三层：host 是用户面对的应用（Claude Code、Claude Desktop 这类）、client 是 host 内部管理连接的模块、server 是提供工具的外部程序。三者之间用 JSON-RPC 2.0 交流。Claude Code 里通常一次性配好几个 server，每个 server 暴露若干工具，主 agent 按需调。

三种传输方式

MCP 定义了三种传输层，选哪种取决于 server 跑在哪里。

stdio：最常用的一种，server 是本地的一个可执行程序，Claude Code 用标准输入输出跟它通信。适合本地跑的工具，比如访问本地文件、调本地数据库客户端。启动速度快、部署零成本，缺点是每个客户端都得自己拉一份进程。

SSE（Server-Sent Events）：server 是一个 HTTP 服务，客户端用 SSE 保持长连接。适合远程 server，尤其是需要服务端主动推送的场景。这种方式在 2025 年下半年开始被 streamable-http 逐步取代，但老 server 里还有大量在用。

streamable-http：2025 年 MCP 协议升级后推出的传输方式，走标准 HTTP，支持双向流。远程 server 现在推荐用这个，既能跑 SaaS 化的公共 MCP，也能挂公司内网做企业级共享。

装一个 MCP server

Claude Code 里加 MCP server 有两种写法。命令行一次性搞定：

claude mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /Users/me/projects

或者手动改 .claude/settings.json，加一个 mcpServers 块：

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/projects"
      ]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    }
  }
}

改完 settings 之后重启 Claude Code，用 /mcp 命令能看到已注册的 server 和它们暴露的工具。

三层 settings 都能配

~/.claude/settings.json 全局生效，项目根目录的 .claude/settings.json 只影响当前项目，.claude/settings.local.json 是不入 git 的个人配置。MCP server 一般放在项目里，团队共享；带 token 的那部分放 local。

常见现成的 MCP

生态到 2026 年已经很成熟了，官方仓库和社区加起来至少有几百个可用 server。挑几个日常用得上的，都是稳定维护、装了就能用的那种：

• filesystem：读写指定目录下的文件，能突破 Claude Code 默认的工作目录限制。适合让 Claude 同时看多个仓库、跨项目搬代码。
• github：查 issue、看 PR、读代码、创建 comment，不用你自己 gh 来 gh 去。评审场景刚需。
• slack：查频道消息、发消息、拉线程历史。跟 Claude 说一句"看看昨天前端频道讨论了什么"，比你翻聊天记录快。
• postgres：只读连一个 postgres，能让 Claude 直接 SELECT 查数据、看 schema。写查询、排查线上问题很好用。
• puppeteer 和 chrome-devtools：让 Claude 操纵浏览器，做端到端测试、抓页面、复现前端 bug。
• sqlite：本地 sqlite 数据库的读写。做小型数据分析、脚本存储很轻。
• memory：给 Claude 一层持久化的记忆层，跨会话保留笔记和事实。
• fetch：让 Claude 能拉网页内容，比自带的 WebFetch 更可控。

一个具体例子：让 Claude 访问工作目录之外

Claude Code 默认只能看当前工作目录，你在 /Users/me/code/app 里启动，它就摸不到 /Users/me/notes/。用 filesystem MCP 就能突破这个限制。

{
  "mcpServers": {
    "notes": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/notes",
        "/Users/me/research"
      ]
    }
  }
}

启动后 Claude Code 里就会多出一批工具，命名规则是 mcp__notes__read_file、mcp__notes__list_directory、mcp__notes__write_file 等。前缀 mcp__<server>__<tool> 是 Claude Code 的固定规范，看到这个前缀就知道是 MCP 来的。

这一步做完之后，你在 Claude Code 里可以直接说"看下 ~/notes/项目复盘/ 里最新那份周报，把结论摘出来发给我"，它会自己去调 mcp__notes__list_directory、找到最新文件、mcp__notes__read_file 读进来、然后总结。整个过程你不用告诉它路径怎么拼、也不用给它 bash，工具的能力边界一目了然。

工具描述里最好写清楚参数含义、返回值格式、错误情况，Claude 是靠 tool schema 里的 description 判断什么时候该用它的。写得含糊，Claude 就用得含糊，甚至干脆不用。

权限：显式 allow 才能用

MCP 工具默认不会自动放行。第一次调用时 Claude Code 会弹权限确认，你可以选允许一次或永久允许。永久允许会写到 settings 的 permissions.allow 数组里：

{
  "permissions": {
    "allow": [
      "mcp__notes__read_file",
      "mcp__notes__list_directory",
      "mcp__github__get_issue"
    ]
  }
}

写权限单独审

读类工具（read、list、search）可以批量放行，但 write_file、delete、execute 这类有副作用的工具建议每次手动确认，或者在 project settings 里显式列出白名单。

什么时候不该用 MCP

不是所有扩展都得走 MCP。判断标准是这个新能力是不是提供了一个新的原语。如果只是把几步 CLI 拼在一起，用 slash command 就够；如果是一段可复用的工作流，写 skill 更合适；只有当你要暴露一个全新的资源（数据库、API、文件系统）时，才值得写 MCP server。这一层区分下一节还会展开。

团队协作里的 MCP

写一个团队共用的 MCP server 通常比让每个人各自装本地脚本更好。原因很直白：一个人升级 server 全组自动生效、认证鉴权可以在 server 侧统一做、审计日志集中收集、有问题一个地方查。

具体到落地上，公司里最常见的做法是：把 MCP server 部署成 streamable-http 服务挂内网、在项目根 .claude/settings.json 里配好 URL 让全组共享、Bearer token 走每个人自己的 .claude/settings.local.json 不入 git。这样即便有人离职，把 token 撤了就够了，不用改共享配置。

常见踩坑

第一次装 MCP 的人经常被这几件事绊住：

• command 找不到：settings 里 command 字段必须是绝对路径或者 PATH 里能查到的可执行文件。用 npx 一般没事，用 python 时如果你有多个 Python 版本，最好写 python3 或者绝对路径。
• 权限没开，工具不出现：MCP server 装了但 /mcp 里看不到工具，多半是 server 起来了但握手失败。开 claude --debug 就能看到具体报错。
• 环境变量传不进去：需要 API key 的 server 必须在 env 块里传，或者启动 Claude Code 时用系统环境变量。别指望 shell 的 .zshrc 会自动加载，Claude Code 起 server 是脱离交互 shell 的。
• 远程 MCP 认证：streamable-http 类型的远程 server 一般需要 Bearer token，在 headers 里配。企业内网的 server 还要注意 CA 证书。