跳至主要內容

安装与快速上手

2026/6/27大约 7 分钟

安装与快速上手

主栈速览

路径一句话深潜
Context7查库文档，防 API 幻觉；ctx7 CLI + Skill，不是默认 MCP03
Playwright CLIAgent 开浏览器、snapshot、点按；不是 Playwright Test 跑 CI04
Gitee MCP托管平台 Issue/PR；git 不管网页侧协作05
Postgres MCPEXPLAIN / 慢查询 / 索引； ad-hoc SQL 用 psql 即可06

谁管什么

Claude Code 会话里用 /mcp、/skills 看连接与 Skill；配置落在磁盘（~/.claude.json / .mcp.json、~/.claude/skills/、~/.claude/rules/）。CC Switch 负责写入并 sync；OAuth、claude mcp add-json 等仍走 Claude Code CLI。

层级干什么工具 / 路径
会话连 MCP、列 tool 数；加载 Skill/mcp、/skills
MCP 配置存 server 定义~/.claude.json（用户级）、.mcp.json（项目级）
Skill / 规则ctx7、Playwright 等指令~/.claude/skills/、~/.claude/rules/
安装与多 Agent写配置、同步到各客户端CC Switch：mcp sync、skills sync
仅 Claude CodeOAuth、add-json、scopeclaude mcp（见下）

换 Provider 后：cc-switch skills sync / cc-switch mcp sync。令牌不要进 git（.mcp.json、.env）。

CC Switch 与 Claude Code（MCP）

CC Switch 管 MCP 有 三种入口，不要混为一谈：

入口实际界面适合
桌面 GUI点 MCP → + → 选 Preset 或 Custom，填表单不想手写 JSON
cc-switch mcp add（CLI）打开 $EDITOR 外部编辑器（未设置时常为 vim），编辑 JSON 模板后保存退出终端用户
cc-switch（无子命令）全屏 TUI，进 MCP 面板后 a 添加、e 编辑（Vim 键位 j/k）已在 TUI 里

CLI 的 mcp add 不是「一步步选 HTTP、填 URL」的向导；那是 GUI 表单 的体验。CLI 会提示 Opening external editor...，你在编辑器里改完 :wq 保存退出（vim）或等价操作。

不想用 vim：临时指定编辑器，例如 EDITOR=nano cc-switch mcp add，或 EDITOR="code --wait" cc-switch mcp add。

操作CC SwitchClaude Code
添加 / 编辑 MCPGUI + 表单；或 mcp add / mcp edit <id>（外部编辑器）；或 TUI 里 a/e—
同步到 live 配置cc-switch mcp sync重开会话或重连
看是否连上—/mcp、claude mcp list
OAuth—claude mcp login <name>
Plugin 自带 MCP不支持/plugin
已有 Claude 配置、想迁入 CC Switchcc-switch mcp import --app claude—
cc-switch mcp list
cc-switch mcp add
cc-switch mcp edit <id>
cc-switch mcp enable <id> --app claude
cc-switch mcp sync
cc-switch mcp validate npx

claude mcp 补充

  • HTTP Remote（≥ 2.1.1）：claude mcp add-json
  • scope：user / project / 默认 local
  • OAuth：claude mcp login github 等

Gitee Remote 示例：

claude mcp add-json gitee '{"type":"http","url":"https://api.gitee.com/mcp","headers":{"Authorization":"Bearer YOUR_GITEE_TOKEN"}}'
claude mcp list && claude mcp get gitee

快速安装

按下面 四个主栈 逐项装。每节结构：准备 → 推荐 → 验证（纯 CLI 可从「推荐命令」起）。

Gitee Remote MCP

是什么： Gitee 官方 Remote MCP，Agent 用 tool 操作 Issue/PR 等；详见 05 章。下面只给安装命令。

上游仓库：oschina/mcp-gitee（2026-06 核对）。Remote URL：https://api.gitee.com/mcp。

准备

  1. Gitee 私人令牌
  2. CC Switch 或 Claude Code CLI 已安装

推荐：CC Switch

方式 A — 桌面 GUI（表单，最直观）

  1. 打开 CC Switch → 顶部 MCP → 右上角 +
  2. Preset 选 Custom（或已有模板则改字段）
  3. Transport 选 http；URL https://api.gitee.com/mcp
  4. Headers 加 Authorization: Bearer <令牌>（Bearer 后有空格）
  5. 勾选 Claude 同步 → 保存

方式 B — CLI cc-switch mcp add（外部编辑器）

  1. 运行 cc-switch mcp add（会打开 $EDITOR，默认常为 vim）
  2. 在 JSON 模板里填 id、name（必填），以及 Remote 的 url / headers 等，例如：
{
  "id": "gitee",
  "name": "Gitee MCP",
  "transport": "http",
  "url": "https://api.gitee.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_GITEE_TOKEN"
  },
  "apps": {
    "claude": true
  }
}

  1. 保存并退出编辑器（vim：:wq）。若报 missing required fields: id, name，说明模板里这两项未填或 JSON 无效。

  2. cc-switch mcp enable gitee --app claude（若 apps.claude 已在模板里为 true，可跳过）

  3. cc-switch mcp sync

方式 C — 不用 CC Switch，直接 Claude Code

见下文 claude mcp add-json。

备选：claude mcp add-json

见上文命令。令牌可来自环境变量，不要写进 shell history。

验证

claude mcp list

Claude Code 里 /mcp。可试：

列出我有权限的 Gitee 仓库

应对应调用 tool list_user_repos（见 05 章工具表）。

勿双装：不要 Remote + 本地 mcp-gitee stdio 同名；主用 Gitee 时不必常开 GitHub MCP。详述 05 章。

Context7 CLI（不是 MCP）

是什么： 查库官方文档的 ctx7 CLI + Skill；详见 03 章 · 是什么。

上游：context7-mcp 仓库内 packages/cli（npm 包名 ctx7）。

推荐命令

Node.js ≥ 18。已带 --cli --claude 时不会再问「MCP 还是 CLI」——直接进入下面流程。

npx ctx7 setup --cli --claude

首次运行 npx 可能提示安装 ctx7@0.5.x，输入 y 即可。

首次安装：OAuth 设备码（默认，会卡住终端）

未传 --api-key 且本机尚未登录时，setup 第一步是 Context7 OAuth 设备码，不是写 Skill。终端大致如下（与你本机一致）：

╭ Sign in to Context7 ─────────────────────────╮
│  Your one-time code:  XXXX-XXXX              │
│  Open: https://context7.com/oauth/device?…   │
╰──────────────────────────────────────────────╯
Press Enter to open the browser, or Ctrl-C to quit...
⠏ Waiting for authorization...

你要做的：

  1. Enter 用默认浏览器打开链接，或手动打开 https://context7.com/oauth/device 输入一次性码
  2. 在网页里 Approve / 授权
  3. 终端出现授权成功后再继续——随后才下载 find-docs Skill、写 context7.md 规则

SSH / 无 GUI：不要 Ctrl-C；把链接和码复制到本机浏览器完成授权。

跳过 OAuth（CI / 已有 Key）：

npx ctx7 setup --cli --claude --api-key YOUR_CONTEXT7_API_KEY

或在 context7.com/dashboard 取 Key 后设环境变量 CONTEXT7_API_KEY。已登录过可单独 ctx7 login 刷新 token。

装完应看到什么（成功样例）

OAuth 完成后，终端应类似（ctx7@0.5.x）：

✔ Authenticated

✔ Downloaded find-docs skill
✔ Context7 CLI setup complete

  Claude Code
    + Skill installed
      /Users/you/.claude/skills/find-docs
    + Rule installed
      /Users/you/.claude/rules/context7.md

说明：

输出含义
AuthenticatedOAuth / API Key 已通过
Downloaded find-docs skill从 Context7 拉取 Skill 包
Context7 CLI setup complete未写入 ~/.claude.json 的 MCP（CLI 路径正常）
find-docs + context7.mdAgent 靠 Skill 触发 + 规则约束 Bash 调 ctx7

没有出现 mcpServers.context7 → 说明没误装 MCP 路径。

--cli 行为摘要：

  • 装 find-docs Skill + 规则 context7.md；不写 MCP server
  • 未加 --cli / --mcp 的裸 npx ctx7 setup 才会交互问 MCP vs CLI

写入位置（agents.ts · 全局）：

内容路径
Skill~/.claude/skills/find-docs/
规则~/.claude/rules/context7.md

CC Switch 用户：ctx7 写 live 目录，不自动进 SSOT；若要统一管理见 03 · CC Switch（import-from-apps 须带目录路径）。

验证

Claude Code 新开一会话：

/skills

列表里应有 find-docs（Enabled）。再手动测 CLI：

npx ctx7 library nextjs "middleware"
npx ctx7 docs /vercel/next.js "middleware authentication"

会话里问 Next.js 文档类问题，模型应走 Bash 调 ctx7，而不是 Context7 MCP tool。

勿双装：已用 --cli 就不要再 setup --mcp。详述 03 章。

Playwright CLI

是什么： Agent 用终端开浏览器、snapshot、点按；详见 04 章 · 是什么。

上游：microsoft/playwright-cli（2026-06 核对）。npm 包：@playwright/cli。

推荐（全局 Skill）

上游 没有 --global：install --skills 写到 当前目录 的 .claude/skills/。要全局（与 ctx7 的 ~/.claude/skills/find-docs 同级），必须先 cd ~：

npm install -g @playwright/cli@latest
cd ~ && playwright-cli install --skills

确认：ls ~/.claude/skills/playwright-cli/SKILL.md。任意项目开 Claude Code → /skills 应有 playwright-cli。

不要在项目根直接跑 playwright-cli install --skills（除非你要 Skill 进仓库 git）。你之前在 molly 里装的那次就是项目级；改全局见 04 · 误装到项目里。

CC Switch（可选）

全局装完后若要纳入 SSOT：

cc-switch skills import-from-apps ~/.claude/skills/playwright-cli -a claude
cc-switch skills sync

须带目录路径；裸跑 import-from-apps 会报错。详见 04 · CC Switch。

验证

playwright-cli --help
playwright-cli open https://demo.playwright.dev/todomvc/
playwright-cli snapshot
playwright-cli close

会话里：

用 playwright-cli 打开 todomvc 演示站，加一条 todo 并截图

勿双装：默认不要同时装 Playwright MCP。详述 04 章。

Postgres MCP（可选）

是什么： EXPLAIN / 慢查询 / 索引推荐； ad-hoc SQL 不必装。详见 06 章 · 是什么。

上游：crystaldba/postgres-mcp。仅当你要 Agent 做 EXPLAIN、慢查询、索引推荐时安装。

claude mcp add postgres \
  -e DATABASE_URI=postgresql://USER:PASS@localhost:5432/mydb \
  -- docker run -i --rm -e DATABASE_URI crystaldba/postgres-mcp --access-mode=restricted

验证：/mcp 约 9 个 tool。详述 06 章。

装完检查

/mcp          # Gitee 在列，工具数 > 0
/skills       # ctx7、Playwright 相关 Skill 为 Enabled

若已装 Skills 03 方案 A，与 Superpowers 不冲突。