mcp-builder

anthropic-mcp-builder 快速入门

Anthropic 官方 MCP 构建 Skill,手把手教你写 Model Context Protocol 服务器,把任意外部 API/数据源接进 Claude。

这是什么?解决什么问题?

mcp-builder 是 Anthropic 在 anthropics/skills 仓库中维护的”教你写 MCP 服务器”的 Skill。Model Context Protocol(MCP)是 Anthropic 推出的开放协议,用于让 AI 模型安全地连接外部工具和数据源——文件、数据库、API、Slack、GitHub 等等。
这个 Skill 包含完整的 MCP 开发指引:Python/Node 双栈脚手架、Schema 校验(JSON Schema 描述工具入参)、stdio/SSE 传输方式选择、调试工具链(Inspector)、测试方法、发布到 MCP Registry。
对小白来说,这个 Skill 解决的是”我想让 Claude 帮我操作公司内网 GitLab,但不知道怎么接”的问题。MCP 协议让这一切标准化——你写一个 MCP Server,告诉 Claude 哪个工具叫什么名字、入参是什么,Claude 就能直接调用。mcp-builder 把这个流程模板化、自动化,几十分钟就能跑通第一个 MCP。

准备工作

• 支持 Agent:Claude Code(主推)、任何支持 MCP 协议的客户端(Cursor、Cline 等)。
  
• 运行环境:Python 3.10+ 或 Node.js 18+;pip install mcp 或 npm install @modelcontextprotocol/sdk。
  
• 可选工具:MCP Inspector(npx @modelcontextprotocol/inspector)用于调试。
  
• 目标场景:接 GitHub API、Slack、Notion、Postgres、内部系统,任意能让 AI “操作”的外部能力。
  

3 步快速上手

第 1 步:安装依赖

# Python<br>
pip install mcp<br>
# 或 Node.js<br>
npm install @modelcontextprotocol/sdk<br>
```<br>
克隆 Skill:<br>
```bash<br>
git clone https://github.com/anthropics/skills.git<br>
cp -r skills/mcp-builder ~/.claude/skills/<br>
```<br>
### 第 2 步:在 Claude Code 中请求脚手架<br>
```bash<br>
claude<br>
```<br>
发起任务:<br>
```<br>
请用 mcp-builder Skill 帮我生成一个 Python MCP Server,叫 "github-issues",提供 list_issues、create_issue、close_issue 三个工具,基于 GitHub REST API。<br>
```<br>
### 第 3 步:配置 Claude Code 加载<br>
把生成的 server 配置到 `~/.claude/mcp.json`:<br>
```json<br>
{<br>
"mcpServers": {<br>
"github-issues": {<br>
"command": "python",<br>
"args": ["path/to/github_issues_server.py"],<br>
"env": {<br>
"GITHUB_TOKEN": "ghp_xxxxx"<br>
}<br>
}<br>
}<br>
}<br>
```<br>
重启 Claude Code,发起:<br>
```<br>
请用 github-issues 工具列出我的 repo 里的所有 open issues。<br>
```<br>
AI 自动调用 MCP 工具,返回 issues 列表。<br>
## 常见踩坑<br>
1. **stdio vs SSE 选错**:本地开发用 stdio(简单),远程服务用 SSE/HTTP(复杂)。Skill 文档有详细对比。<br>
2. **Schema 不严格**:工具入参 schema 必须严格 JSON Schema,否则客户端拒绝调用。<br>
3. **错误处理不到位**:工具内部要 try/except,失败时返回结构化错误(MCP 标准格式),不是直接抛异常。<br>
4. **敏感信息泄露**:API Key 等敏感数据走 env 变量,不要硬编码或日志输出。<br>
5. **传输不稳定**:SSE 长连接可能断,要实现重连逻辑。<br>
6. **混淆 MCP 与 Function Calling**:Function Calling 是 OpenAI 的,MCP 是 Anthropic 推动的开放协议,语法相近但生态不同。<br>
## 初级用法<br>
- **接 GitHub API**:让 Claude 直接看 PR、改 issue。<br>
- **接 Postgres**:让 Claude 直接跑 SQL 查询(注意 read-only 限制)。<br>
- **接 Slack**:让 Claude 直接发消息到指定频道。<br>
## 高级玩法<br>
- **多 MCP 组合**:同时加载 github、jira、slack,Claude 跨工具编排工作流。<br>
- **私有 Registry**:企业内部 MCP Registry,统一管理工具版本与权限。<br>
- **认证与授权**:OAuth 2.0 流程,每个用户单独 token,Skill 文档有详细示例。<br>
## 小技巧<br>
- 用 MCP Inspector(`npx @modelcontextprotocol/inspector`)调试,可视化测试每个工具。<br>
- Tool 描述写清楚"何时使用",AI 触发准确率提升 50%。<br>
- 工具入参 schema 提供 `description` 字段,AI 才能正确传参。<br>
- 长任务用 async,避免阻塞主进程;Skill 文档有 async/await 示例。<br>
- 关注 MCP 官方文档的 Breaking Changes,SDK 升级时及时跟进。<br>
## 常见问题 FAQ<br>
**Q1: 这个 Skill 跟 anthropic-mcp-builder 有什么关系?必须装吗?**<br>
A: Skill 是给 AI Agent 用的"技能包",能告诉 Agent 怎么按特定规范工作。**不是必须装**——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。<br>

**Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?**<br>
A: anthropic-mcp-builder 来自 Anthropic,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。<br>

**Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?**<br>
A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。<br>

**Q4: 怎么验证 Skill 装对了?**<br>
A: 在 Agent 中输入"列出已加载的 Skill"或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。<br>

**Q5: 这个 Skill 有许可证吗?能商用吗?**<br>
A: 取决于 anthropic-mcp-builder 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。<br>

## 参考链接<br>
- [官方仓库](https://github.com/anthropics/skills)<br>
- [该 Skill 目录](https://github.com/anthropics/skills/tree/main/skills/mcp-builder)<br>
- [MCP 协议规范](https://modelcontextprotocol.io/)<br>
- [Python SDK](https://github.com/modelcontextprotocol/python-sdk)<br>
- [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)<br>
- [MCP Inspector](https://github.com/modelcontextprotocol/inspector)<br>
- [Claude Code MCP 配置](https://docs.claude.com/en/docs/claude-code/mcp)<br>
- [Anthropic MCP 介绍](https://www.anthropic.com/news/model-context-protocol)<br>