Claude Code MCP Server 指南：安全连接 SaaS、GitHub 与团队文档

MCP Server 可以把 Claude Code 从一个本地编程助手，变成能够读取 GitHub Issue、搜索团队文档、连接 Notion、Google Drive、CRM 或内部 API 的工作入口。它很强，但也很容易出事故。错误的 scope、写进仓库的 token、过宽的 OAuth 权限、Windows 上无法启动的 npx、一次返回太多内容导致的 10,000 token warning，都会让原本漂亮的演示变成难维护的流程。

这篇文章不只介绍“怎么连上”。重点是如何安全导入：先用最小 scope，避免在 .mcp.json 中放秘密，使用 /mcp 检查连接和授权，把输出限制在可审查的范围内，并为团队留下能复用的配置。

MCP 在 Claude Code 中改变了什么

MCP 是 Model Context Protocol，用来让 AI 客户端连接外部工具和数据源。Claude Code 作为 MCP client，调用 MCP server 暴露的工具。这样它就可以在会话中访问 Issue、文档、指标、SaaS 或内部服务。

但这也改变了风险边界。没有 MCP 时，Claude Code 主要看到仓库和你贴进去的上下文。有了 MCP，它可能看到客户资料、产品指标、会议记录、支持工单或内部文档。所以第一步不是安装最多的 server，而是决定“这个项目应该看什么数据，用什么权限，看完之后谁负责确认”。

权限设计建议和 Claude Code 权限指南 一起看；安全边界可以参考 Claude Code 安全实践。

连接方式	适合场景	注意点
stdio	本地通过 npx、Python 或内部命令启动	Windows 常需要 cmd /c npx
http	远程 MCP Server、SaaS、OAuth	必须检查 workspace 和授权范围
sse	兼容旧的 SSE 服务	新集成通常优先使用 HTTP

先选择正确的 scope

claude mcp add 可以指定 --scope local、--scope project、--scope user。这个选择决定 server 对哪些项目可见。

scope	含义	推荐用途
local	只在当前项目和当前机器使用	个人验证、客户项目、含私密信息的连接
project	写入 .mcp.json，可以跟仓库共享	团队共享 server 定义，但不共享秘密
user	用户级别，所有 Claude Code 项目可用	真正通用的个人工具

默认从 local 开始。团队需要统一名称和命令时，再升级到 project。project scope 的 server 会触发 project server approval，这是安全检查，不是多余步骤。

# 个人验证，影响范围最小
claude mcp add --scope local --transport stdio repo-files -- npx -y @modelcontextprotocol/server-filesystem ./docs

# 团队共享，配置进入 .mcp.json
claude mcp add --scope project --transport http team-docs https://mcp.example.com/mcp

# 只有真正跨项目通用时才用 user
claude mcp add --scope user --transport http personal-notes https://mcp.example.com/mcp

Windows 设置：用 cmd /c npx 包住 stdio server

Windows 上经常出现一个现象：PowerShell 中 npx 能运行，但 Claude Code 启动 MCP stdio server 时找不到命令。实务上建议用 cmd /c npx。

claude mcp add --scope local --transport stdio repo-files -- cmd /c npx -y @modelcontextprotocol/server-filesystem "C:\Users\masa\work\claudecode-lab\docs"

写成 .mcp.json 时，把 cmd 和参数拆开，并转义 Windows 路径中的反斜杠。

{
  "mcpServers": {
    "repo-files": {
      "type": "stdio",
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\masa\\work\\claudecode-lab\\docs"
      ],
      "env": {}
    }
  }
}

不要一开始就把整个用户目录交给 filesystem server。先给 docs、reports 或测试仓库。需要写入时，再结合 Claude Code Hooks 指南 做危险命令拦截。

远程 MCP、OAuth 与 /mcp 检查

Notion、Google Drive、GitHub、CRM 等远程 SaaS，通常用 HTTP transport。连接命令很短，但真正重要的是授权确认。

claude mcp add --scope local --transport http notion https://mcp.notion.com/mcp

添加后，在 Claude Code 中运行 /mcp。这里可以看到连接状态、OAuth 状态、暴露的 tools。OAuth 需要浏览器授权时，从 /mcp 进入流程，然后回到 Claude Code 检查结果。

/mcp

# 必须确认：
# - server 是否 connected
# - OAuth 是否 authenticated
# - 授权的是哪个 workspace
# - 暴露的 tools 是否符合预期
# - 是否出现不需要的 write/admin 权限

内部服务如果用 bearer token，可以通过 header 传入，但不要把 token 写进共享文件。

claude mcp add --scope local --transport http crm-readonly https://mcp.example.com/readonly \
  --header "Authorization: Bearer $CRM_READONLY_TOKEN"

团队共享的 .mcp.json 应该只保存连接定义。

{
  "mcpServers": {
    "customer-docs": {
      "type": "http",
      "url": "https://mcp.example.com/customer-docs"
    },
    "github-readonly": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@example/github-readonly-mcp"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_READONLY_TOKEN}"
      }
    }
  }
}

实例1：GitHub 与 Notion 做 Issue 调查

最容易产生价值的场景，是减少 Issue、PR、规格文档之间的来回切换。Claude Code 可以通过 GitHub MCP 读取 Issue，通过 Notion 或文档 MCP 查找需求背景，然后先输出风险和确认点。

读取 GitHub issue #248，并在产品文档中搜索相关需求。
暂时不要修改代码。
请返回：
1. 可能涉及的文件
2. 已经明确的需求
3. 还不明确的问题
4. 最小安全实现方案

重点是“先读，不要马上改”。MCP 给了 Claude Code 更多上下文，也可能让它更快地做出错误判断。把阅读、比较、提问、实现分成阶段，团队更容易审查。

实例2：Google Drive 文档生成提案草稿

咨询、培训、受托开发通常有很多会议记录、旧提案和价格说明散在 Drive 里。只读的 Drive 类 MCP 可以帮助 Claude Code 整理提案草稿。

搜索「2026-05 Customer A」文件夹。
生成一份提案大纲：
1. 客户的5个主要问题
2. 可能的实现范围
3. 必须确认的未知事项
4. 培训、实现支援、运维支援三个方案

姓名、邮箱、精确合同金额请打码。

这里的安全点是限制文件夹、只读、发送前人工 review。MCP 负责加快整理，不负责最终对外承诺。

实例3：只读指标用于内容和产品决策

MCP 也可以连接产品指标或内容分析 API。不要把生产写入权限交给演示用流程。对于分析，读-only endpoint 已经足够。

claude mcp add --scope local --transport http product-metrics https://mcp.example.com/readonly-metrics \
  --header "Authorization: Bearer $METRICS_READONLY_TOKEN"

查看过去14天的流入来源、文章PV、转化点击。
按主题聚类页面。
推荐接下来5个文章主题，并给出支撑每个建议的指标。
同时指出数据可能不稳定的地方。

这类连接很适合商业化。它把博客或产品运营变成反馈循环，而不是凭感觉发布内容。

处理 10,000 token warning

MCP tool 返回内容太大时，Claude Code 会出现 10,000 token warning。常见原因是文档搜索返回全文、Issue 列表太长、抓取整页 HTML、数据库查询没有限制行数。

第一步不是提高上限，而是减少输出。

最多返回10条结果。
每条只包含标题、URL、更新时间、匹配原因。
不要返回正文。需要时我会指定某一条再读取。

临时深度分析可以提高 MAX_MCP_OUTPUT_TOKENS，但不要作为日常设置。

MAX_MCP_OUTPUT_TOKENS=50000 claude

$env:MAX_MCP_OUTPUT_TOKENS = "50000"
claude

如果日常流程总是需要提高上限，应该改 MCP server：分页、过滤、摘要、按目的提供 endpoint。

常见失败例

第一，.mcp.json 写入秘密。project scope 的配置会共享到仓库，不能放 API token 或 DB 密码。

第二，随便使用 --scope user。这样可能让客户A的连接出现在客户B项目中。先用 local。

第三，把远程文档当成指令。MCP 读到的外部文本可能包含 prompt injection。要明确要求 Claude Code 把外部文档当数据，而不是命令。

第四，OAuth 成功后不检查 /mcp。浏览器授权成功不等于授权范围正确。必须检查 workspace、tools 和权限。

第五，依赖超大输出。巨大的 MCP 响应很慢，也难以 review。业务流程应该返回摘要，而不是全部数据。

排查命令

先看 server 列表，再看单个 server，再进 /mcp 检查认证。

claude mcp list
claude mcp get repo-files

Claude Code 会话中运行：

/mcp

如果 project server approval 选错了，可以重置选择。

claude mcp reset-project-choices

最小 smoke test：

只检查 repo-files MCP 连接。
列出允许目录正下方最多10个文件名。
不要读取文件内容，不要修改任何文件。

商业化角度：卖安全流程，不卖连接按钮

MCP 接近收入，因为它连接的是团队真正使用的系统。单纯说“我能安装 MCP Server”不够强。更好的表达是：“我能把 GitHub、Notion、Google Drive 和内部 SaaS 安全接到 Claude Code，让团队每周都能用，而不是只做一次演示。”

可以设计三层产品：

• 模板包：.mcp.json 示例和安全检查清单
• 团队审查：GitHub、Notion、Drive、权限边界 review
• 导入支援：scope、OAuth、hooks、监控、培训一起落地

个人使用者先在测试文件夹跑通 filesystem 示例。团队则从一个只读 SaaS 和一个 project-scoped .mcp.json 开始，再和 Claude Code Harness Engineering 的安全足场结合。

本文按 Claude Code 官方 MCP 文档中的 claude mcp add、scope、.mcp.json、/mcp、OAuth、project server approval、MAX_MCP_OUTPUT_TOKENS 整理。实践原则很简单：小 scope、先只读、不共享秘密、每次连接都验证。