ARTICLE · 1232638

只会改本地文件的 AI 程序员,终于长出手了——Claude Code MCP 接入实战手册

发布时间：2026-10-23 05:10:49 最近访问：2026-10-23 05:10:31

上篇文章发出去之后，朋友装好 Claude Code 用得挺顺手。他发来新问题：让它把最近的改动推上去、顺手开个 PR。它回了一句：我没有访问 GitHub 的工具。朋友懵了：你不是 AI 吗？

说实话，这不是它笨。AI 编程助手的瓶颈从来不在"脑子"——模型能读懂代码、能写代码，但默认状态下它的活动范围只有你电脑上的文件和终端。GitHub、数据库、Notion、浏览器，全是它够不着的地方。MCP（Model Context Protocol）就是给它接手脚的协议。

一句话讲清 MCP：它是 Anthropic 定的一个开放协议，规定"外部工具该怎么把自己介绍给 AI"。Claude Code 通过 MCP 连上各种服务器，就能像调本地工具一样调用外部服务。你可以把它理解成 AI 界的 USB-C 接口——以前每个外设要配一根专用线，现在一套协议全通吃。

图1：左边是没有 MCP 的能力圈，右边是接上 MCP 之后能摸到的东西。

一、MCP 到底解决什么问题

先看没有 MCP 的 Claude Code。它其实已经很强了：读本地文件、编辑代码、跑命令、用 Bash 工具，这几件事干得利索。但它也有明确的边界——GitHub 上的 Issues 它看不见，云数据库连不上，外部 API 调不了，实时数据（天气、行情）更是无从谈起。上一篇文章里那个邮箱校验 Bug 是纯本地问题，所以它能搞定；一旦需求里带一句"顺便在 GitHub 上开个 Issue"，它就熄火了。

接上 MCP 之后，这个边界就没了。查 GitHub Issues、开 PR、查 SQLite 和 PostgreSQL、读写 Notion、Slack、浏览器自动化、实时天气地图……原来的能力一样不少，外接能力随接随用。而且这些能力不是写死的：MCP 服务器是独立进程或独立服务，开发者写一个，所有支持 MCP 的 AI 工具都能用。

二、十分钟接上第一个 MCP

配置文件只有两个位置，认准这张表：

级别	路径	作用范围
用户级	`~/.claude.json`	所有项目
项目级	`.claude/mcp.json`	当前项目

推荐项目级。原因后面讲最佳实践的时候细说，先记住一件事：不同项目用不同的服务集合，互不污染。

配置的过程比想象中简单得多——你根本不用手写 JSON，直接说人话：

帮我添加 GitHub MCP 服务器，我的 token 是 ghp_xxx

它自己会把配置写进 .claude/mcp.json。SQLite 也一样：

添加一个 SQLite 数据库服务器，数据库文件在 ./data/app.db

配完之后问一句"现在有哪些可用的 MCP 服务器？"，它会列出清单。更硬核的验证方式是敲诊断命令 /doctor，它会做一次全身检查：Claude Code 版本、Node 版本、每个 MCP 服务器的连接状态和工具数量，连不上的直接标 ✗ 并给出原因。

配置生效之后，用起来就是一句自然语言的事：

帮我在 GitHub 上创建一个 Issue

它会问你要仓库地址、标题、描述，然后动手。

三、三种传输方式怎么选

MCP 服务器有三种接法，区别在"服务器跑在哪"：

传输方式	服务器位置	配置要点	适用场景
STDIO	本地进程	command + args（npx 拉起）	绝大多数本地工具
HTTP	远程服务	url + transport + headers 鉴权	团队内部/云端服务
SSE	远程服务	url + transport（服务器推送）	流式推送场景

STDIO 是主流。大多数官方服务器都是 npm 包，Claude Code 用 npx 直接把进程拉起来，进程之间走标准输入输出通信，简单可靠。HTTP 和 SSE 适合你自己部署的远程服务——团队共用一个 MCP 服务器时，改一处配置全员生效，比每人本地跑一份强。

四、拿 GitHub 开刀：第一个实战

GitHub 服务器是上手 MCP 最经典的选择，配置长这样：

{  ”mcpServers”: {    ”github”: {      ”command”: ”npx”,      ”args”: [”-y”, ”@modelcontextprotocol/server-github”],      ”env”: {        ”GITHUB_PERSONAL_ACCESS_TOKEN”: ”your-token”      }    }  }}

Token 在 github.com/settings/tokens 申请，权限按需勾选。

配置好之后试个完整流程：

帮我把当前的修改推送到 GitHub，然后创建一个 PR，标题是”添加新功能”

它会自己检查 git 状态、建分支、提交、推送、调 MCP 工具创建 PR，最后把 PR 链接甩给你。一条指令走完平时半小时的活儿。

数据库也是高频场景。接上 SQLite 服务器之后：

查询数据库中最近注册的 10 个用户

它连库、执行查询、格式化结果一气呵成。SELECT、连表、排查数据问题，都变成对话了。常用的还有 filesystem（指定目录的文件访问）、puppeteer（浏览器自动化，能打开网页截图分析页面设计）、brave-search（联网搜索）。

五、四个最佳实践

项目级配置优先。前端项目接浏览器测试，后端项目接数据库，各用各的 .claude/mcp.json。更重要的是它能提交到 Git——团队成员克隆项目后直接用同一套服务，新人零配置。全局配置堆得多了，迟早乱。

密钥环境变量化。这条是红线：token 永远不要硬编码进配置文件。配置一旦提交到 Git，密钥就等于公开了。正确姿势是配置文件里只写引用：

{  ”env”: {    ”GITHUB_TOKEN”: ”$GITHUB_TOKEN”  }}

版本锁定。npx -y 默认永远拉最新版 MCP 服务器，新版本可能引入不兼容改动，服务器也可能突然改名或下架。在包名后加 @版本号，锁定经过验证的版本：

{  ”args”: [”-y”, ”@modelcontextprotocol/server-github@1.2.3”]}

文档化配置。项目里 MCP 服务器多了之后，在 .claude/ 下放一个 README.md，写清每个服务器的用途、需要的 token、去哪申请。新成员上手的沟通成本能砍掉一大半。

六、坏了怎么查

MCP 出问题有个方便之处：诊断这件事本身也可以交给它。

我的 MCP 服务器连接不上了，帮我检查一下

它会自动查配置文件格式、验证环境变量、测试服务器连接、给出修复建议。GitHub 工具调用失败、sqlite 一直显示连接中，都能这样问。

常见的坑集中在四类：

问题	可能原因	解决
服务器未连接	配置文件 JSON 格式错误	检查语法（多一个逗号就废）
工具无法调用	权限不足	检查 env 里的密钥变量
连接超时	网络问题	检查 URL 或网络
进程崩溃	服务器代码错误	看服务器日志

自查利器还是 /doctor。输出一目了然：哪个服务器连上了、暴露了多少个工具、哪个失败了、失败原因是什么，末尾还附建议。它甚至能区分"12 个工具正常"和"连不上，数据库文件路径不对"这两种状态——别自己瞎猜，先跑 /doctor。

七、Claude Code vs Claude Desktop

很多人是从 Claude Desktop（桌面版聊天应用）认识 MCP 的。两个都支持 MCP，但对开发者来说差异很大：

特性	Claude Code	Claude Desktop
项目级配置	✓ 支持	✗ 不支持
自然语言管理	✓ 支持	✗ 需手动编辑
诊断工具	✓ `/doctor`	✗ 无
热重载	✓ 自动重载	✗ 需重启应用
适用场景	开发工作流、CI/CD	日常聊天、办公

一句话：写代码选 Claude Code，MCP 的管理体验完全不在一个量级；Desktop 的 MCP 适合非开发场景。

八、该不该接：一张决策表

你的情况	建议
日常要碰 GitHub、数据库、外部 API	必接，收益立竿见影
团队协作，希望统一工具环境	项目级 mcp.json 提交到 Git，全员共享
有内部服务想给 AI 用	写一个 MCP 服务器（HTTP/SSE），一次接入多个 AI 工具可用
纯本地开发、离线环境	可以先不折腾，本地能力够用
担心 token 泄露	接之前先立规矩：密钥只走环境变量

最后一句话：上一篇文章说 Claude Code 是"坐在终端里等你下指令的工程师"；接上 MCP 之后，这个工程师算是拿到了公司所有系统的工牌。