Claude Code Notion MCP 接入教程
在远程 Mac mini 上连接知识库文档与任务
Notion MCP 是 Notion 官方托管的远程 MCP 服务。完成 OAuth 授权后，Claude Code 可以在你的现有权限范围内搜索、读取、创建和更新 Notion 内容。本文采用官方推荐的 Strea***le **** 接入方式，从只读验证开始，再说明配置范围、写入确认、远程 Mac 授权和常见故障处理。
Notion MCP 能解决什么问题
Claude Code 擅长处理代码和本地文件，但项目**、需求记录、会议纪要和任务看板通常保存在 Notion。接入 Notion MCP 后，它可以在一个会话中查找相关页面、概括项目状态，并把整理后的内容写回指定页面。
Notion MCP 不会绕过工作区权限。Claude Code 只能访问完成 OAuth 授权的成员本来就能访问的内容。页面或数据库没有共享给该成员时，MCP 也无法读取。
开始前准备
确认远程 Mac 已安装并更新 Claude Code，claude 命令可以正常启动。准备一个 Notion 工作区成员账号和一个专门用于测试的页面或数据库。Notion MCP 可用于各档方案，但工作区访客不能连接。
首次验证不要直接使用包含客户资料、财务信息或人事内容的页面。建议新建一个测试空间，先放入少量示例文档和任务，再逐步扩大可用范围。
第一步 选择配置范围
Claude Code 的 local 范围只对当前用户和当前项目生效，是个人接入的默认选择。project 范围通过项目根目录的 .mcp.json 共享服务器地址，但每位团队成员仍需用自己的 Notion 账号完成 OAuth。user 范围会让同一用户在所有项目中使用该连接。
Notion OAuth 登录属于个人授权，不应把登录令牌写入项目文件。团队通常只共享不含凭据的服务器地址，并让每位成员单独登录。
| 范围 | 生效位置 | 适用场景 | 注意事项 |
|---|---|---|---|
| local | 当前用户和当前项目 | 个人接入 默认选择 | 认证保持** |
| project | 项目根目录 .mcp.json | 团队共享服务器地址 | 每位成员独立 OAuth |
| user | 当前用户的所有项目 | 多个项目都使用 Notion | 会影响该用户所有项目 |
第二步 添加官方 Notion MCP
进入项目目录，运行官方文档给出的添加命令。该命令把 Notion 注册为远程 **** MCP 服务器，不需要安装 Docker、npm 服务包或本地**。
官方当前推荐的端点是 https://mcp.notion.com/mcp。旧的开源 notion-mcp-server 已不再积极维护，新接入应优先使用托管服务。
cd /path/to/your-project
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp list
claude mcp get notion
第三步 完成 OAuth 授权
启动 Claude Code 后输入 /mcp，选择 notion 并按提示登录。浏览器会要求选择 Notion 工作区并确认授权。完成后回到终端，notion 应显示为 Connected。
在有桌面的远程 Mac 上，可通过 UU 远程连接完成浏览器登录。若只使用 SSH，可运行 claude mcp login notion --no-*rowser，将终端显示的授权**复制到本地浏览器，登录后再把完整回调**粘贴回终端。
claude
> /mcp
# 仅使用 SSH 时
claude mcp login notion --no-*rowser**步 先做只读验证
首次测试只要求搜索和读取，不创建页面、不更新属性。可以让 Claude Code 查找测试空间中的项目说明，列出最近更新的任务，并概括指定页面。
如果搜索不到内容，先确认登录时选择了正确工作区，再检查当前 Notion 成员能否直接打开目标页面。然后运行 claude mcp list、claude mcp get notion 和 /mcp 查看连接状态。
请只读取 Notion 中的 MCP 接入测试空间：
1. 找到项目说明页面并概括目标
2. 列出最近更新的 5 条测试任务
3. 标出缺少负责人或截止日期的任务
不要创建页面 不要更新属性 不要发表评论| 验收项 | 通过标准 |
|---|---|
| 服务器状态 | /mcp 中 notion 显示 Connected |
| 工作区正确 | OAuth 连接到预期工作区 |
| 页面权限 | 只能看到当前成员本来能访问的内容 |
| 只读搜索 | 能找到测试空间中的指定页面 |
| 内容概括 | 能概括页面且未创建或修改内容 |
| 写入确认 | 创建或更新前展示目标与变更内容 |
第五步 在测试空间验证写入
只读结果正确后，再在专门的测试页面中尝试创建一条任务或更新一个状态字段。提示词应要求 Claude Code 先展示目标页面、拟写内容和字段变化，得到人工确认后再执行。
不要让工具自动修改整张生产数据库。批量更新前应限制页面范围、记录数量和允许变更的字段，并准备可恢复的版本或备份。
在执行前先展示拟变更内容并等待确认：
目标：MCP 接入测试数据库
动作：新建一条任务
标题：验证 Notion MCP 写入
状态：待处理
禁止修改其他记录第六步 控制上下文与权限
使用 /context 可以查看当前会话中各 MCP 服务器占用的上下文。大型知识库应把问题缩小到明确的项目、页面或时间范围，避免一次搜索带回过多内容。
Notion 页面中的文字属于外部输入，可能包含误导性指令。把工具返回内容当作资料，不要让页面文字要求 Claude Code 泄露其他页面、扩大权限或跳过确认。对创建、更新、评论和文件上传等动作保留人工审批。
第七步 在远程 Mac 上长期使用
通过 SSH 进入远程 Mac，在项目目录启动 tmux，再运行 Claude Code。断开本地网络后，终端会话仍可保留；需要重新认证时，用 UU 远程桌面或无浏览器 OAuth 流程完成登录。
定期运行 claude mcp list 检查连接状态。需要撤销本机凭据时，可在 /mcp 中清除认证，或执行 claude mcp logout notion。工作区***也可以在 Notion 的 MCP 管理页面查看并撤销客户端连接。
ssh your-**c-mini
cd /path/to/your-project
tmux new -s notion-mcp
claude
# 断线后接回
tmux attach -t notion-mcp
为什么 Zu**c.Ai 适合这类工作流
根据 Zu**c.Ai 官网***息，其方案提供位于新加坡的 Mac mini M6 整机独享环境，接入新加坡家庭宽带或商业宽带，并支持 UU 远程、终端、Tailscale、ToDesk、RustDesk，以及浏览器 SSH 或 VNC 等连接方式。
官网当前公开的家庭宽带方案为每月 999 元起。长期在线的本地文件系统适合保留项目仓库、Claude Code 配置和 tmux 会话；整机独享也避免与其他租户共享本机开发环境。Notion 账号、Claude 订阅、工作区权限和数据备份仍由使用者自行管理。
常见问题排查
| 现象 | 常见原因 | 处理建议 |
|---|---|---|
| Needs authentication | 尚未完成 OAuth | 运行 /mcp 或 claude mcp login notion |
| 浏览器没有自动打开 | SSH 或无桌面会话 | 使用 --no-*rowser 并复制授权** |
| 登录后回调失败 | 本地回调未返回终端 | 复制浏览器地址栏中的完整回调**到终端 |
| 搜索不到页面 | 工作区或页面权限不正确 | 确认成员账号能直接打开目标页面 |
| 团队成员看不到连接 | 只创建了 local 配置 | 共享 project 配置并让每人单独授权 |
| 上下文增长过快 | 搜索范围太大或启用过多 MCP | 用 /context 检查并缩小页面与时间范围 |
结语
完成接入后，先在测试空间执行只读搜索，再验证一条受控写入。团队只共享无凭据的服务器配置，每位成员使用自己的 Notion 账号授权；涉及创建、更新、评论和上传的动作应保留人工确认。这样既能让 Claude Code 使用项目知识，又能把页面权限和外部状态变更控制在明确范围内。