从零玩转 Claude Code：MCP 配置 + SKILLS 编写实战（TaoToken 统一 Key 接入版）

1. 从零上手 Claude Code 到底卡在哪MCP 与 SKILLS 的真实门槛Claude Code 是一个跑在终端里的 AI 编程助手它能读你本地的代码、执行命令、改文件而 MCPModel Context Protocol是它连接外部工具的标准协议SKILLS 则是你用 CLAUDE.md 给它写的“岗位说明书”。适合谁适合已经会用命令行、想让 AI 真正动手干活而不是只聊天的开发者。但很多人第一次配的时候卡点非常集中环境变量填错、MCP 服务连不上、CLAUDE.md 写了但模型不触发。我自己踩过的坑是一开始以为把 API Key 塞进.env就完事结果 Claude Code 启动后一直报401排查半天才发现是 Base URL 和模型名对不上。后来换成 TaoToken 统一 Key 接入把 Anthropic 协议通道固定下来才稳定跑通。这篇就按“环境准备 → TaoToken 接入 → MCP 配置 → SKILLS 编写 → 验证 → 排障”的顺序把每一步的可复制片段都给你。先说清楚整体链路Claude Code 本体负责对话和工具调度MCP 服务端比如 GitHub MCP负责提供外部能力SKILLSCLAUDE.md负责告诉模型“什么时候该调用哪个工具、输出什么格式”。三者缺一不可。很多人只配了 MCP 却没写 SKILLS结果模型根本不知道要去调 GitHub问它“分析我的仓库”它只会干聊。反过来只写 SKILLS 没配 MCP模型想调也调不到会直接报工具不存在。环境侧你需要 Node.js 和 Bun。Node.js 建议 20 以上Bun 用来跑 Claude Code 的启动脚本。Windows 用户如果不想折腾 WSL可以用 Git Bash 模拟类 Unix 终端但要注意 Claude Code 只认 Windows 原生路径Git Bash 路径要转成双反斜杠。这些细节后面配置章节会逐个给命令。TaoToken 在这里的角色是统一 Key 和 API 通道你不需要分别去申请各家模型的 Key也不用担心 Base URL 写错。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。把这两点记住后面 auth.json 和 .env 都围绕它来填。这一节先把“为什么难”讲透难点不在装软件而在配置项的语义。ANTHROPIC_BASE_URL决定请求打到哪ANTHROPIC_API_KEY决定身份ANTHROPIC_MODEL决定用哪个模型三者必须来自同一个通道否则就是 401 或 model not found。MCP 的.mcp.json里command和args决定服务端怎么起env决定它拿什么凭证。CLAUDE.md 的触发词和指令决定模型的行为边界。理解这四层后面就是填空。2. TaoToken 前置准备统一 Key 与 auth.json 修改步骤在写 MCP 和 SKILLS 之前必须先把 Claude Code 的模型通道打通否则后面所有验证都会失败。TaoToken 提供统一的 API 通道你只需要一个 Key就能让 Claude Code 走 Anthropic 协议访问模型。这一步的核心是拿到 Key、写对 Base URL、改对 auth.json。先去控制台创建 API Key。打开 https://taotoken.net/api-keys 登录后点创建复制那串以sk-开头的 Key。注意这串 Key 只显示一次复制后存到密码管理器。如果你用的是 Claude Code 官方 CLI凭证通常放在~/.claude/auth.json或项目级.claude/auth.json如果你用的是源码版则通过.env注入。两种方式我都给。先看 auth.json 方式。文件路径在 Windows 下是C:\Users\你的用户名\.claude\auth.jsonmacOS/Linux 是~/.claude/auth.json。内容结构如下把sk-你的Key替换成刚复制的{ anthropic: { apiKey: sk-你的Key, baseURL: https://taotoken.net/api } }注意 baseURL 结尾不要带/v1Claude Code 会自己拼/v1/messages。如果你多写了/v1会变成/v1/v1/messages直接 404。这是最常见的坑之一。再看.env方式适合源码版或想用环境变量覆盖的场景。在项目根目录创建.envANTHROPIC_API_KEYsk-你的Key ANTHROPIC_BASE_URLhttps://taotoken.net/api ANTHROPIC_MODELclaude-sonnet-4-20250514 ANTHROPIC_DEFAULT_SONNET_MODELclaude-sonnet-4-20250514 ANTHROPIC_DEFAULT_HAIKU_MODELclaude-haiku-4-20250514 ANTHROPIC_DEFAULT_OPUS_MODELclaude-opus-4-20250514 API_TIMEOUT_MS3000000 DISABLE_TELEMETRY1 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC1模型 ID 必须和 TaoToken 通道支持的名称一致。如果你不确定当前有哪些模型可以去模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 实际发一条消息验证能返回就说明 ID 对。我实测下来Sonnet 系列做代码任务性价比最高Haiku 适合快速补全Opus 留给复杂重构。如果你用的是 Claude Code 官方安装方式还需要确认settings.json里的模型配置。路径在~/.claude/settings.json加上{ model: claude-sonnet-4-20250514, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key } }三件套必须齐全Base URL、Key、Model ID。缺任何一个都会在启动时报错。配完后先别急着上 MCP用一条最简单的请求验证通道。在终端执行curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-4-20250514,max_tokens:64,messages:[{role:user,content:ping}]}返回里有content字段且不是 401就说明通道通了。这一步过了再往下走能省掉后面 80% 的排障时间。如果这里就 401检查 Key 有没有多余空格、baseURL 有没有写错、anthropic-version 头有没有带。3. MCP 配置实战.mcp.json 与 GitHub MCP 服务端接入MCP 是 Claude Code 连接外部工具的协议配置入口是项目根目录的.mcp.json。这一节以 GitHub MCP 为例给你可复制的 JSON 片段并说明每个字段的含义。为什么选 GitHub MCP因为它能直观展示“模型调用外部工具”的完整链路你问一句“分析我的仓库”模型通过 MCP 去调 GitHub API拿回真实数据再组织回答。先拿 GitHub Personal Access Token。登录 GitHub右上角头像 → Settings → 左侧最底部 Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic)。Note 随便填Expiration 选 30 或 90 天Scopes 勾repo和read:user。生成后复制ghp_开头的字符串只显示一次。然后在 Claude Code 项目根目录创建.mcp.json{ mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_TOKEN: ghp_你的Token } } } }字段解释command是启动命令npx会自动下载并运行包args里-y表示跳过确认modelcontextprotocol/server-github是官方 GitHub MCP 服务端env.GITHUB_TOKEN是服务端读取的凭证。注意 Token 不要提交到 Git建议.mcp.json加进.gitignore或者用环境变量引用。如果你用的是 Claude Code 官方 CLIMCP 配置也可以放在~/.claude.json或项目级.claude/settings.json的mcpServers字段结构一样。源码版则读项目根目录的.mcp.json。两种方式选一种不要重复配否则会起两个服务端实例。配完后验证挂载。官方 CLI 用claude mcp list源码版用./bin/claude-haha mcp list成功会显示github: npx -y modelcontextprotocol/server-github - ✓ Connected。如果显示Failed to connect先手动跑一遍npx -y modelcontextprotocol/server-github看是不是网络或 Node 版本问题。Node 建议 20 以上低于 18 会报fetch is not defined。MCP 服务端暴露的工具是标准化的GitHub MCP 通常提供读取用户仓库列表、获取仓库目录树、读取指定文件内容。模型会根据你的自然语言自动选择工具但前提是 SKILLS 里写清楚触发条件。这就是下一节的内容。这里先记住.mcp.json只负责“把工具接进来”不负责“什么时候用”后者归 CLAUDE.md 管。还有一个细节MCP 服务端启动是懒加载的第一次调用会慢几秒因为 npx 要下载包。如果你网络环境下载慢可以先全局装npm i -g modelcontextprotocol/server-github然后把command改成nodeargs改成[/path/to/server-github/dist/index.js]。这样启动更快也避免每次 npx 拉包。4. SKILLS 编写CLAUDE.md 目录结构与触发规则SKILLS 在 Claude Code 里就是 CLAUDE.md 文件它相当于给模型的一份“技能说明书”。你写清楚触发词、描述、指令模型在匹配到触发词时就会按你规定的流程调用 MCP 并输出指定格式。这一节给你完整的目录结构和示例代码直接复制就能用。文件位置项目根目录的CLAUDE.md。如果项目有子目录也可以在子目录放CLAUDE.mdClaude Code 会按层级合并。全局技能放~/.claude/CLAUDE.md对所有项目生效。建议先写项目级验证通过后再抽到全局。创建文件touch CLAUDE.md然后写入以下内容。这段是 GitHub 项目分析技能触发词、描述、指令三段式# Claude Code 技能库 ## GitHub 项目智能分析与代码审查 ### 触发词 分析github项目 审查github仓库 github项目介绍 ### 描述 自动调用 GitHub MCP 服务分析指定 GitHub 用户或仓库生成结构化项目分析报告包括技术栈、目录结构、README 质量和代码改进建议。 ### 指令 1. 当用户输入分析github项目 用户名/仓库地址时必须自动调用已配置的 github MCP 服务。 2. 如果输入的是用户名获取该用户所有公开仓库的基本信息名称、描述、更新时间、星数、语言。 3. 如果输入的是完整仓库地址额外获取仓库目录结构、读取 README.md 内容、检查根目录是否有 requirements.txt 等依赖文件。 4. 生成结构化报告严格按以下 Markdown 格式输出 # 项目分析报告 ## 基本信息 - 仓库名称: - 最后更新: - 主要语言: - 星数/分支数: ## 技术栈分析 - 核心框架: - 依赖库: - 项目类型: ## 目录结构 简洁目录树只保留核心文件和一级目录 ## README 质量评估 - 完整性评分1-10分: - 缺失内容建议: ## 架构与代码建议 - 1. - 2. 报告要简洁专业重点突出技术细节和可操作建议。所有信息必须来自 MCP 的真实返回结果禁止编造。关键点触发词要具体别用“分析”这种泛词否则模型会误触发。描述里写清楚“调用哪个 MCP”指令里写清楚“输入什么、输出什么格式”。最后那句“禁止编造”很重要能显著降低模型幻觉。目录结构建议这样组织方便扩展多个技能项目根/ ├── CLAUDE.md # 主技能文件 ├── .mcp.json # MCP 配置 ├── .claude/ │ └── skills/ # 可选拆分复杂技能 │ └── github.md └── src/如果技能多了可以把每个技能拆成独立 md 文件放.claude/skills/然后在 CLAUDE.md 里用import .claude/skills/github.md引入。这样维护更清晰。但初学者先用单文件跑通再说。写完 CLAUDE.md 后重启 Claude Code 让它重新加载。然后输入触发词测试。如果模型没反应检查三点触发词是否完全匹配、MCP 是否 Connected、CLAUDE.md 是否在项目根目录。这三点排查完基本都能解决。5. 验证请求与常见报错排查401、local proxy failed、reading choices配置写完必须验证否则你不知道是通道问题还是 MCP 问题。这一节给你一次完整的验证流程以及四个高频报错的对照排查。每个报错我都给真实错误信息和解决步骤。先验证模型通道。在 Claude Code 里输入一句简单的话比如“你好回复 ok”。如果返回正常说明 TaoToken 通道通了。如果报401 Unauthorized错误信息通常是API Error: 401 {error:{type:authentication_error,message:invalid x-api-key}}排查检查 auth.json 或 .env 里的 Key 有没有多余空格、有没有过期、baseURL 是不是https://taotoken.net/api。如果 Key 是从控制台复制的注意别把前后引号也复制进去。改完重启 Claude Code。第二个高频错误是local proxy failedError: local proxy failed to start: listen tcp 127.0.0.1:xxxx: bind: address already in use这是端口被占用。Claude Code 会起一个本地代理转发请求如果上次没退干净端口还占着。解决找到占用进程杀掉。Windows 用netstat -ano | findstr :端口号再taskkill /PID 进程号 /FmacOS/Linux 用lsof -i :端口号再kill -9 进程号。或者直接重启终端。第三个是reading choices相关错误Error: reading choices: unexpected end of JSON input这通常是 MCP 服务端返回了非 JSON 内容比如 npx 下载失败打印了错误日志。排查手动跑npx -y modelcontextprotocol/server-github看输出是不是正常 JSON-RPC。如果是网络问题换全局安装方式。另外检查.mcp.json的args有没有写错包名。第四个是 OAuth 相关Error: OAuth token exchange failed: invalid_grant如果你用的是需要 OAuth 的 MCP 服务端Token 过期或 scope 不对会报这个。GitHub MCP 用的是 PAT 不是 OAuth所以一般不会遇到。如果遇到重新生成 Token 并确认 scope 勾了repo。验证 MCP 是否真的被调用可以在 Claude Code 里输入分析github项目 你的GitHub用户名预期表现模型先调用 github MCP 的仓库列表工具拿回数据再按 CLAUDE.md 的格式输出报告。如果它只干聊没调工具说明 CLAUDE.md 触发词没匹配上或者 MCP 没 Connected。回到第 3 节用mcp list确认。再验证单仓库深度分析分析github项目 你的用户名/某个仓库名预期它会额外拉 README 和目录树。如果报告里出现“我无法访问该仓库”但仓库明明是公开的检查 Token 的reposcope 有没有勾或者仓库是不是私有而 Token 没权限。最后给你一个排查顺序口诀先 curl 验通道再 mcp list 验挂载再触发词验技能最后看日志定位。按这个顺序90% 的问题能在五分钟内定位。6. 长期编码与 Agent 场景把配置沉淀成可复用工作流跑通一次不算完真正省时间的是把 MCP 和 SKILLS 沉淀成可复用工作流。这一节讲怎么把配置抽到全局、怎么给不同项目写不同技能、以及长期用 Coding Plan 的接入方式。全局技能把通用的 GitHub 分析技能放到~/.claude/CLAUDE.md这样所有项目都能用。项目级 CLAUDE.md 只写项目特有的规则比如“本项目用 pnpm 不用 npm”“提交信息用中文”。Claude Code 会合并两层项目级优先。MCP 全局配置官方 CLI 支持claude mcp add命令把 GitHub MCP 加到用户级配置所有项目共享。源码版可以把.mcp.json放到用户目录用符号链接引到各项目。这样不用每个项目复制一遍 Token。多技能拆分当 CLAUDE.md 超过 200 行建议拆到.claude/skills/目录每个技能一个文件。比如github-analysis.md、code-review.md、commit-message.md。主 CLAUDE.md 用import引入。这样模型加载时按需读取不会一次塞太多。长期编码场景建议用 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它适合每天都要用 Claude Code 写代码的人比按量计费更划算。接入方式还是三件套Base URL 用https://taotoken.net/apiKey 用 Coding Plan 专属 KeyModel ID 按套餐支持的填。配好后和普通 Key 用法完全一样。Agent 场景如果你想让 Claude Code 自动跑测试、自动改 bug、自动提 PR需要在 CLAUDE.md 里写清楚“什么条件下执行什么命令”。比如“当用户说‘修复测试’时先跑npm test根据失败信息改代码再跑一次确认通过”。配合 MCP 的 GitHub 工具还能自动创建分支和 PR。但注意别让它直连生产库所有写操作先在本地或测试环境验证。最后给一个实用技巧把常用触发词做成 shell alias比如alias cc-analyzeclaude 分析github项目减少输入。或者写个脚本把仓库地址作为参数传进去。这样每天用的时候就是一条命令的事。配置沉淀的核心是“一次配好到处能用”。TaoToken 统一 Key 的好处就在这里你不需要为每个项目重新申请 Key也不用担心 Base URL 写错。把 auth.json 和 .mcp.json 配好CLAUDE.md 写好剩下的就是专注写代码。