1. 前言

在将 AI 助手融入日常工作流时，我们追求的是无缝与高效。Claude 作为强大的对话式 AI，其潜力远不止于聊天。通过 Claude Code 的工具使用（Tool Use）能力，我们可以让它操作外部应用，例如我们最喜爱的知识库——Notion。

但是，在调用任何 notion.create_page 或 notion.search 指令之前，我们必须先完成一个关键的、一次性的步骤：建立连接。

这篇文章的核心目的，就是指导你如何通过一个简单的命令，安全、可靠地为 Claude 授予访问 Notion 的能力。这个连接是后续所有自动化操作的基础，它确保了：

• 安全性：通过标准的 OAuth 2.0 流程授权，你无需手动生成、复制和粘贴 Notion API Token，避免了敏感凭证泄露的风险。
• 持久性：一次连接，长期有效。后续的脚本或对话可以直接调用 Notion 工具，无需重复授权。
• 便捷性：整个过程由 Claude CLI 或桌面应用自动处理，体验流畅。

让我们开始吧。

2. 基础准备

在开始连接之前，请确保完成以下两个简单的准备步骤。

2.1 更新 Claude CLI / Desktop

MCP (Message-based Communication Protocol) 是 Claude Code 中较新的功能，它负责管理与外部服务的安全通信。请确保你的客户端版本足够新（≥ v0.7.0）以支持此功能。

对于 CLI 用户：

打开你的终端，运行以下命令进行升级：

pip install --upgrade claude-cli

对于 Claude Desktop 用户：

打开桌面应用，通过菜单栏检查更新，确保你运行的是最新版本。

2.2 检查 Notion 侧权限

为了让 Claude 能够访问你的 Notion 内容，你需要：

1. 拥有编辑权限：确保你对希望 Claude 操作的 Notion 工作区（Workspace）拥有管理员或成员权限。
2. 预先选好授权范围：想好你希望授权给 Claude 的具体页面或数据库。一个最佳实践是专门创建一个数据库（例如，命名为 “AI Drafts”）或一个顶级页面（例如 “Claude Inbox”），仅将 Claude Integration 授权给这个特定范围，以遵循最小权限原则。

3. 一条命令添加 MCP 服务器

准备工作就绪后，打开你的终端，执行这关键的一条命令：

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

让我们来分解这个命令：

• claude mcp add: 这是 claude-cli 中用于添加一个新的 MCP 服务的指令。
• --transport http: 指定通信协议为标准的 HTTP/S 请求。这是最常用、最通用的方式。
• notion: 这是你为这个连接设置的本地别名。你可以随意命名，比如 my-notion、work-notion 等。后续所有与 Notion 相关的指令都将使用这个别名作为前缀，例如 notion.help。
• https://mcp.notion.com/mcp: 这是 Claude 官方提供的、用于连接 Notion 的公共 MCP 端点。它是一个托管在云端的安全代理，负责处理 Claude 与 Notion API 之间的 OAuth 流程和数据交换。

高级选项：如果你偏好使用 Server-Sent Events (SSE) 以获得更实时的双向通信体验，可以将命令调整为： claude mcp add --transport sse notion https://mcp.notion.com/mcp/sse

执行命令后，CLI 会确认 MCP 服务器已添加，但此时的状态是”未连接”。

4. 首次 OAuth 授权流程

现在，我们需要触发一次授权，让 Notion 知道你允许 Claude 访问你的账户。

1. 在你的 Claude 对话或终端中，尝试调用任何一个以你刚才设置的别名开头的工具指令。最简单的就是请求帮助：

   notion.help

2. 此时，Claude CLI 或桌面应用会检测到 notion 服务尚未授权，并自动打开你的默认浏览器，跳转到 Notion 的登录和授权页面。

3. 在浏览器中，登录你的 Notion 账户（如果尚未登录），然后选择你想要授权的工作区 (Workspace)，接着选择你希望授予权限的具体页面或数据库。

4. 点击 “Allow access” 按钮。

5. 授权成功后，浏览器会显示一个成功页面，提示你可以返回到你的应用。此时，你可以关闭这个浏览器标签页。

回到 Claude，连接已经悄然建立。整个过程你没有接触到任何 API Token，非常安全。

5. 验证连接是否生效

如何确认连接真的成功了？我们可以用 mcp 子命令来检查。请注意，以下命令只检查状态，不会对你的 Notion 内容进行任何写入或修改操作。

首先，列出所有已配置的 MCP 服务：

claude mcp list

你应该能看到刚才添加的 notion 服务，以及它的通信方式：

Available MCP servers:
- notion (http)

接下来，获取 notion 服务的详细信息：

claude mcp get notion

你会看到一段 JSON 输出，其中最重要的字段是 status。如果一切顺利，它应该显示为 connected。

{
  "name": "notion",
  "transport": "http",
  "url": "https://mcp.notion.com/mcp",
  "status": "connected",
  "last_error": null
}

看到 status: "connected"，恭喜你，大功告成！Claude 现在已经拥有了与你的 Notion 账户安全通信的能力。

6. 常见问题 & 排错

如果在设置过程中遇到问题，可以参考下表进行排查：

7. 后续可做的事（预告）

现在，连接的桥梁已经架设完毕，一片广阔的自动化大陆正等待我们去探索。在接下来的文章中，我们将展示如何利用这个连接做一些真正酷的事情：

• 管理笔记和任务：使用 notion.create_page、notion.append_block_children 和 notion.search 等工具，直接在对话中创建、更新和查找 Notion 内容。
• 构建自动化流水线：结合本地文件系统工具，实现一个 “Markdown → Notion” 的摘要流水线，自动将本地的 *.md 文件内容总结并写入到 Notion 数据库。
• 自托管 MCP 服务：对于有特殊需求（如私有化部署、离线环境、企业合规）的开发者，我们将探讨如何自托管 MCP 服务器，实现完全可控的端到端连接。

8. 结语

我们通过一条命令和一次简单的 OAuth 网页授权，就完成了 Claude 与 Notion 之间可信连接的建立。这种现代化的集成方式，彻底告别了手动管理 Access Token 的繁琐与不安全。

这个连接是所有后续 Notion 自动化的基石。现在，你的 Claude 已经准备好成为你真正的 Notion 助理了。

在下一篇文章中，我们将深入探讨如何实际调用 Notion 的各种工具指令，完成内容的写入、查询与同步。敬请期待！