Claude Code MCP 实战：几分钟接上真工具

一句话总结

Model Context Protocol（MCP）让 Claude Code 伸到仓库之外：数据库、GitHub、监控、设计稿都能直接读。你用 claude mcp add 注册一次 server，选一个 transport（远程服务用 http，本地进程用 stdio）和一个 scope（local、project 或 user），之后 Claude 就能以 mcp__servername__toolname 的名字调用它的工具。先装一个、证明它真省了一次手动复制粘贴，再加更多。只想要命令就直接看下面的”具体步骤”；想看推荐清单就看”第一天值得装的 server”。

这篇讲什么

怎么把 MCP server 真正接到 Claude Code——不是抽象讲 MCP 是什么，而是讲具体 claude mcp add 怎么用、三种 transport（stdio、http、sse）、scope 标志（local / project / user），以及第一天该装哪几个 server。常见的翻车点：看完 MCP 规范一兴奋，一口气装五个，权限弹窗每几秒一次，一气之下全关掉。这篇先装一个跑通，再讲怎么没摩擦地加更多。

核心概念：

• MCP（Model Context Protocol）：Anthropic 开源的标准，把工具、文件、数据暴露给 LLM。现在 Claude Code、Claude Desktop、Cursor 等众多客户端都支持它。
• claude mcp add：在 Claude Code 里注册 server 的 CLI 子命令。
• Transport：stdio（本地子进程，跑在你机器上的工具）、http（流式 HTTP，远程/云服务的推荐 transport）、sse（较老的 HTTP server-sent events，现已被 http 取代、不建议再用）。
• Scope：local（仅当前项目、私有于你——默认值）、project（写进仓库的 .mcp.json、提交后团队共享）、user（你的所有项目、私有于你）。
• 工具命名：注册的工具在 Claude Code 工具列表里叫 mcp__servername__toolname。

这篇适合谁看

走完Claude Code 新手指南、想把 agent 能干的事拓展到读改文件以外的人。尤其是你常常往 chat 里贴数据库查询结果、GitHub PR 评论、Sentry 报错堆栈——这些正是 MCP 要消灭的拼贴动作。

什么时候适合用

一次会话里同样的”从别的工具复制、粘进 chat”动作出现了两次。数据库查询、GitHub PR 评论、报错日志、设计稿、仓库外文件访问——每一个都是 MCP server 的候选。别预防性地装；看到自己又在重复手动动作了再装。官方文档也是这么说的：当你发现自己又在从别的工具往 chat 里复制数据时，就该接一个 server 了。

先选对 transport 和 scope

两个前置决定能省掉大部分困惑：选哪个 transport，选哪个 scope。

Transport	用于	Claude 怎么连	状态（2026 年 6 月）
stdio	本地工具和脚本（filesystem、本地数据库客户端、自写的 Python server）	spawn 一个子进程、走 stdin/stdout 通信	稳定，本地 server 默认
http	远程/云服务（GitHub、Sentry、Notion、Stripe）	连一个 URL，支持 OAuth 和 Bearer header	所有远程 server 的推荐选项
sse	只提供 SSE 的老式远程 server	连一个 SSE URL	已弃用——server 有 http 就用 http

Scope	在哪加载	是否团队共享	存在哪
local（默认）	仅当前项目	否	~/.claude.json（按项目路径归类）
project	仅当前项目	是，通过版本控制	仓库根的 .mcp.json
user	你的所有项目	否	~/.claude.json

两个命名提醒，因为老教程和截图说法不一致：现在的 --scope local 以前叫 project，现在的 --scope user 以前叫 global。看到旧名字在脑子里换算一下。优先级是 local > project > user，所以同名时 local 覆盖项目共享的 project 条目。

开始前准备

• Claude Code 装好能用（claude --version）。不行的话看新手指南。
• PATH 上有 Node 18+——多数参考 stdio server 走 npx。
• 项目作用域的 server 要在 git repo 里、你愿意把 .mcp.json 提交进去。
• 要接的东西的凭据（GitHub 细粒度 PAT、Postgres 连接串）。拿到再开始装。

具体步骤

1. 先看当前注册了哪些 server，知道起点：

claude mcp list

2. 加 filesystem 参考 server，scope 给 user，这样每个项目都能用。它暴露指定目录的读写工具：

claude mcp add filesystem --scope user \
  -- npx -y @modelcontextprotocol/server-filesystem ~/work

-- 分隔符必须有：后面是 Claude Code 走 stdio 时要 spawn 的命令。少了 --，Claude Code 会把 server 自己的 flag 当成自己的选项去解析，注册就失败了。

3. 在 Claude Code 里 /mcp 重载（或重启会话）。确认 server 已连上：

claude mcp list
# filesystem: ... - ✓ Connected

4. 试一个工具。在 Claude Code 里问：用 filesystem 工具列一下 ~/work 里的文件。 第一次会请求权限——只读工具可以选”始终允许”，免得每次调用都被弹窗打断。

5. 加一个走 HTTP 的远程服务。对多数开发者来说 GitHub 价值最高。截至 2026 年 6 月，老的 @modelcontextprotocol/server-github npm 包已弃用；GitHub 现在提供官方远程 server，用细粒度 personal access token 走 HTTP 连接：

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

到 GitHub Settings → Developer settings → Fine-grained tokens 生成 token，权限只给你想让 Claude 碰的那些仓库。如果某个 server 用 OAuth 而不是 token（Sentry、Notion、Linear），就别加 header，改在 chat 里跑 /mcp 走浏览器登录。

6. 加一个该让队友共享的项目作用域 server——只读数据库连接是最典型的例子。这会在仓库根写一个 .mcp.json：

claude mcp add db --scope project \
  -- npx -y @bytebase/dbhub --dsn "$DATABASE_URL"

验 claude mcp list 里它 scope 是 project、.mcp.json 在仓库根。.mcp.json 提交；真正的连接串放在环境变量里、别内联（见下方配置模板的密钥处理）。

7. server 不正常时按这个顺序排查：claude mcp list（注册了吗、连上了吗？）→ claude mcp get servername（命令或 URL 是啥？）→ 在 chat 里跑 /mcp 看实时状态、重新鉴权。远程 server 会话中途断了，Claude Code 会用指数退避自动重连（最多五次）；stdio server 是本地进程，不会自动重连。反复断连看Claude MCP server 断连。

第一天值得装的 server

三个 server 就能覆盖日常大部分”复制粘进 chat”的痛点。这三个用满一周之前，先别急着加第四个。

Server	Transport	干掉的手动动作	安装
filesystem	stdio	从仓库外贴日志和文件	npx -y @modelcontextprotocol/server-filesystem <目录>
GitHub	http	贴 PR 评论、issue、diff	远程 https://api.githubcopilot.com/mcp/ + PAT
数据库（dbhub）	stdio	”我看一眼 schema”式的复制粘贴	npx -y @bytebase/dbhub --dsn <连接串>

为啥是这三个：filesystem 让 agent 摸到当前仓库外的文件（日志、scratch 目录）。GitHub 干掉”把 PR 评论粘到 chat”的循环。数据库 server 把”我查一下 schema 长啥样”从粘贴变成查询。（@bytebase/dbhub 是已弃用的 @modelcontextprotocol/server-postgres 的当前维护替代品，支持 Postgres、MySQL、SQL Server、MariaDB、SQLite。）

还有一个值得知道：@playwright/mcp（stdio）给 Claude 一个真浏览器去测流程、截图，做前端时很顺手：

claude mcp add playwright -- npx -y @playwright/mcp@latest

三个 server 的配置模板

如果你更愿意直接改 JSON 而不是跑三条 claude mcp add，这是一份项目作用域的 .mcp.json。注意密钥都以环境变量引用、绝不内联——Claude Code 在加载时会展开 ${VAR}（以及 ${VAR:-默认值}）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${CLAUDE_PROJECT_DIR:-.}"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
    },
    "db": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
    }
  }
}

每个开发者在自己环境里设 GITHUB_PAT 和 DATABASE_URL，提交的文件就不带任何密钥。项目作用域 server 第一次会让每个队友确认是否信任——这是安全机制、不是 bug。

完成后检查

• claude mcp list 里每个 server 是已连接，不是 error、disconnected 或 ⏸ Pending approval。
• 工具在 chat 里以 mcp__servername__toolname 出现——问”你有哪些工具”它能列出来。
• 权限弹窗合理：只读工具第一次同意后自动允许，写工具每次问。
• .mcp.json 提交了，密钥留在环境变量里、没内联。
• agent 不用提醒就会用 MCP 工具。数据库 server 在线却老让你贴查询结果，就前几次显式点名工具：“用 db 工具查……”。

怎么跨项目复用

• 日常、整机通用的 server 放 user scope——filesystem 和你个人的 GitHub 连接是好人选，它们会跟着你进每个项目。
• 每个仓库提交一份最小 .mcp.json（project scope），带项目专属 server：该项目的数据库、它的 issue tracker（如果有 MCP）。
• 在 CLAUDE.md 里写 MCP 用法：“查数据库问题用 db MCP。” 显式指引帮 Claude 第一轮就选对工具。
• 新流行的 server 先在 local scope 自己试，再在 project scope 共享。烂 server 浪费整个团队的时间。

一句话的循环：发现手动粘贴动作 → 找对应 MCP server → claude mcp add 用对 transport 和 scope → claude mcp list 验 → 头几次显式点名工具 → 习惯让 agent 自己用。

容易踩的坑

• 第一天装五个。 权限疲劳直接把实验杀死。先装一个、证明有用、再加。
• 密钥直接写进 .mcp.json 提交。 用环境变量 ${VAR} 引用，真值留在 .env（保持不被 git 跟踪）。
• stdio 的 claude mcp add 忘了 -- 分隔符。 后面的命令被当 flag 解析，注册失败。
• 队友要用的 server 用了 --scope local。 local 不共享；仓库级 server 用 project，个人跨项目的用 user。
• 还在用已弃用的 npm 包。 @modelcontextprotocol/server-github 和 @modelcontextprotocol/server-postgres 都不再维护——改用 GitHub 的远程 HTTP server 和 @bytebase/dbhub。
• 断开的 server 放着不管。 要么修，要么 claude mcp remove 删掉。挂着的 server 让工具列表混乱（断连排查）。

FAQ

• 只写代码也需要 MCP 吗？ 不需要。MCP 是伸到代码库外的——数据库、API、外部文件。纯写代码用 Claude Code 的内置工具就够了。
• 该选哪个 transport？ 本地跑的东西用 stdio（filesystem、本地 DB 客户端、自己的脚本）。任何远程/云服务用 http，因为它支持 OAuth 和 Bearer header。只有远程 server 没别的选项时才用 sse，因为 SSE 已弃用。
• 默认 scope 是哪个？ local——server 只在当前项目加载、私有于你，存在 ~/.claude.json。要团队共享用 project（写 .mcp.json），要所有项目都能用就用 user。
• 需要 OAuth 的远程 server 怎么鉴权？ 用 claude mcp add --transport http 加上，然后在 chat 里跑 /mcp 走浏览器登录。token 会安全存储并自动刷新。
• 能自己写 MCP server 吗？ 能。协议开源、有官方 Python 和 TypeScript SDK，Claude Code 还能用 mcp-server-dev 插件帮你搭骨架（/mcp-server-dev:build-mcp-server）。
• MCP server Cursor 也能用吗？ 能。协议共享，所以同一批 server 都能用，只是注册 UI 和 Claude Code 的 CLI 不一样。

相关阅读

• Claude Code 新手指南
• Claude Code 项目设置
• Claude MCP server 断连
• Claude Code slash 命令

外部参考：Claude Code MCP 文档 · Model Context Protocol

标签: #AI 编程 #教程 #Claude Code

相关文章

AI 工具教程

AI 生成更新日志：从 commits 到人愿意读完的 release note

把 git log 变成读者真会读完的两层 release note，再用一道评审抓出被藏起来的 breaking change。

2026/05/24 #AI 编程 #工作流

AI 工具教程

AI 协作数据库迁移——可回滚、有回填、能测

AI 在迁移上最常错的三件事：可回滚、回填策略、大表上的 NOT NULL。

2026/05/24 #AI 编程 #工作流

AI 工具教程

用 AI 写事故复盘，又不冲淡教训

一套用 AI 在 60 分钟内出一份无指责复盘初稿的流程，同时不让模型把难听的真相圆掉。

2026/05/24 #AI 编程 #工作流

AI 工具教程

AI 解 merge 冲突：什么时候能信自动合

AI 几分钟能解掉大多数 merge 冲突，真正的功夫在于知道哪 10% 它绝不能碰，以及怎么抓住「靠删一边来合并」这种故障。

2026/05/24 #AI 编程 #工作流

AI 工具教程

AI on-call 排障：从被叫醒到修好不慌

凌晨 3 点被 page 了？一套实测过的 AI 流程——分流、给假设排序、破坏性命令前的冷静协议，再把聊天沉淀成 runbook。

2026/05/24 #AI 编程 #工作流

AI 工具教程

AI 写 PR 描述——从 diff 到能审

把 git diff 变成 reviewer 真愿意打开看的 PR 描述，prompt 不会编出根本不存在的 test plan。

2026/05/24 #AI 编程 #工作流