Claude Code 实战第一课：MCP 外接工具 + 自定义命令

生命不息，折腾不止。Claude Code 光会聊天可不够——今天给它接上 MCP 外部工具、再存几条自定义命令，把它从「会说话的助手」调成「能自己把活干完的工程师」。

RAG 实战六课收官之后，咱们开个新系列：Claude Code 实战。上一课结尾也把话说死了——第一课不聊安装，那个基本盘早就铺好了，直接上两个进阶玩法：MCP 和 自定义 Slash Command。

这俩东西，一个解决「手脚问题」，一个解决「习惯问题」。搞明白它俩，你才算是真的会用 Claude Code，而不是把它当个高级聊天框。

一、先看清短板：Claude Code 到底缺啥

Claude Code 本身其实已经挺能干：读你项目里的文件、改代码、跑 bash、写测试，这些它天生就会。但真拿到生产上用，你会很快发现它有两个卡脖子的问题。

第一个，手不够长。 它默认只能碰「你自己仓库里的东西」。GitHub 上的 issue、数据库里的数据、网页上的内容、Notion 里的文档——这些都在它够不着的地方。你想让它「去 issue #123 看看需求再改」，结果只能你自己打开 issue 页面、复制粘贴给它，它再对着你贴的那坨文本干活。一个需求复制一次，烦都能烦死。

第二个，没养成习惯。 那些你天天干的活——「看看改动写个 commit message」「把这段代码过一遍安全检查」——每次都得敲一大段交代，少一句它就糊弄。其实这些是标准流程，不该每次现教。

MCP 解决第一个（给 Claude 接上外部工具），Slash Command 解决第二个（把高频流程存成一条命令）。这俩合起来，就是「工程值拉满」的分水岭。

二、MCP 是啥：给 Claude 接工具的「万能插口」

MCP（Model Context Protocol，模型上下文协议） 是个开放标准，2024 年底由 Anthropic 推出来，现在快成各家 AI 工具接外部世界的通用协议了。

用大白话说，MCP 约等于「USB 接口」。以前你想让 Claude 连一个新系统，得给每个系统单独写一套对接代码；现在只要那个系统「支持 MCP」——也就是官方或社区提供了一个 MCP server——Claude Code 一行命令就能接上，当场多出几个能调用的工具。

它分两个角色：

MCP server（提供方）：把某个系统的能力包成一个服务，对外暴露一堆「工具」，比如 GitHub 的 server 暴露 search_issues、get_file 这些工具。
MCP client（使用方）：就是 Claude Code 自己，负责连上 server、把里面的工具「翻译」成它能调用的东西。

连接方式常见两种：

HTTP（远程）：很多 SaaS 官方直接给个 MCP 端点，Claude Code 通过网络连过去，适合 GitHub、Notion 这类云服务。
stdio（本地进程）：用 npx 或 uvx 在你本机起一个 server 进程，适合 filesystem（读写本地目录）、fetch（抓网页）这种跑在本地的东西。

一句话总结：接了 MCP，Claude 就能直接读 issue、查数据库、抓网页，不用你再当人肉搬运工。

三、动手：三行命令接上第一个 MCP server

先给 Claude 接个最实用的——filesystem，让它能读写某个目录。stdio 方式的命令长这样：

1
2
3

# 让 Claude 通过 MCP 读写 /home/you/projects 这个目录
claude mcp add --transport stdio filesystem \
  -- npx -y @modelcontextprotocol/server-filesystem /home/you/projects

注意中间那个 --，它前后的东西要分清：-- 之前是 Claude Code 自己的选项（--transport、--env、--scope），-- 之后是「启动 server 的命令」，原样传过去。不写 --，server 自带的参数（比如 -y）就会被 Claude Code 当成自己的选项解析掉，直接报错。

再补两个常用的：

# fetch：让 Claude 能联网抓网页、读 URL 内容
claude mcp add --transport stdio fetch \
  -- npx -y @modelcontextprotocol/server-fetch

# github：需要你的 personal access token
claude mcp add --transport stdio github \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx \
  -- npx -y @modelcontextprotocol/server-github

装完怎么确认连没连上？两条路：

1	claude mcp list # 终端里看装了哪些 server

再进到 Claude Code 会话里敲 /mcp，看每个 server 状态是不是 connected。显示 failed 的话，多半是 token 填错或启动命令拼错，照着提示改。

作用域怎么选？ claude mcp add 默认写 local（只对当前项目目录生效），另外还有：

--scope project：写进项目根目录的 .mcp.json，可以 git 提交，整个团队共用同一套。
--scope user：全局所有项目都能用。

团队共享的正确姿势是提交一份 .mcp.json，长这样：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./docs"]
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  }
}

配置里支持 ${VAR} 和 ${VAR:-默认值} 展开，token 这类敏感值可以留成环境变量占位，别把真实 key 提交进仓库。

四、自定义命令：把高频流程存成一句话

MCP 装的是「手」，Slash Command 养的是「习惯」。一条自定义命令，本质就是一个 Markdown 文件：文件名就是命令名，文件正文就是 prompt。

项目级放 .claude/commands/<名字>.md（跟着仓库走，提交给团队）
个人级放 ~/.claude/commands/<名字>.md（所有项目都能用）

写在 commands/review.md 里，就能随时敲 /review 触发。正文第一行之前可以加 YAML frontmatter，常用字段这几个：

字段	干啥
`description`	一句话说明，`/help` 里显示
`argument-hint`	提示这条命令该跟什么参数
`allowed-tools`	预授权哪些工具，如 `Bash(git:*)`
`model`	指定跑这条命令用哪个模型

正文里还能塞三种「动态内容」：

$ARGUMENTS / $1 / $2：把 /命令参数 里的参数替换进来；
@路径：引用某个文件的内容进上下文；
`!命令`：先执行一段 bash，把输出塞进上下文（注意前面那个 ! 前缀）。

举个能直接抄的「提交」命令，存成 .claude/commands/commit.md：

---
description: 看改动并生成 commit
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *) Bash(git diff *)
argument-hint: "[可选的提交说明]"
---

先看看当前工作区改了啥：

!`git status --short`

!`git diff --stat`

根据上面的改动，写一条清晰的 commit message，然后执行：

git add -A
git commit -m "<你写的 message>"

如果改动里出现了 .env、密钥、大文件，先停下来问我，不要直接提交。

以后想提交，不用再敲那些固定前摇，直接 /commit 一句走完。再给你一个带参数的「安全审查」命令，存成 .claude/commands/security-review.md：

---
description: 对指定代码做安全检查
argument-hint: "[文件或目录]"
---

仔细审查 $ARGUMENTS 里的代码，按清单逐项查：

1. 有没有硬编码的密钥、Token、密码；
2. 有没有 SQL 注入、命令注入、路径穿越风险；
3. 依赖里有没有已知漏洞。

把发现的问题按严重程度从高到低排，每条给出具体位置和修复建议。

用法 /security-review src/app.py，$ARGUMENTS 就会被替换成 src/app.py。

一个容易懵的点：官方新文档里，把「自定义命令」并进了 Skills，推荐写法变成了 .claude/skills/<名字>/SKILL.md。但老的 .claude/commands/<名字>.md 照样能用、功能基本一致。你按哪个写都行，别看到两份文档就慌。

五、上生产前的几个提醒

MCP 和命令都是「很能打但需要留个心眼」的东西，开用之前记住四条：

Scope 是覆盖不是合并：同一个 server 名在 local / project / user 三处都配了，只取优先级最高的那一条（local > project > user），字段不会合并。你「项目里改了 env 没生效」，八成是 local 里还压着一条旧的。
凭据别进 git：团队共享用 .mcp.json + ${VAR:-默认值} 占位，token 走环境变量；第一次用项目级的 server，Claude Code 会弹一个「是否信任」的确认，别无脑点是——先看它到底要连什么、引用了什么。
防 prompt injection：fetch 这类会抓外部网页的 server，抓回来的内容可能夹带恶意指令。别让 Claude 对「刚抓下来的网页内容」盲目照做、写成代码，该核对核对。
allowed-tools 是「预授权」不是「限权」：它只是免掉那一次调用的人工确认，并不会把工具池收窄；真想锁死，得用 disallowed-tools 或权限里的 deny 规则。

另外提一嘴模型来源：如果你不像我一样有 Anthropic 官方账户，可以用国内中转站按量付费跑 Claude Code——比如 ai.aklibk.com（国内直连、免绑卡、人民币按量付费），设好 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 两个环境变量即可，跟上面 MCP、命令这些完全不相干、各管各的。

到这，Claude Code 第一课就完了：MCP 给它接了「手脚」，自定义命令给它养了「习惯」。回头看，你已经能写出一个「接了 GitHub + 联网、一句话自动提交」的 Claude Code 了。

生命不息，折腾不止。第一课装好了手脚和习惯，下一篇《Claude Code 实战第二课：Hooks 钩子自动化，把「人盯」变成「自动把关」》——聊聊怎么在 .claude/settings.json 里配 hooks，让 Claude 每次动文件、跑命令前后自动挂上检查，改代码先跑测试、提交前先跑 lint。下篇见。