Notion (MCP)

本指南将启用 Open WebUI 与您的 Notion 工作区进行交互——利用 模型上下文协议 (Model Context Protocol, MCP) 搜索页面、读取内容、创建文档以及管理数据库。

为什么选择此集成？

此集成使用了官方的 Notion MCP 服务器，其特色在于 自动 Markdown 转换。当 AI 读取 Notion 页面时，它接收到的是整洁、结构化的 Markdown，而不是原始的 JSON 块，这显著提高了模型理解和总结笔记的能力。

社区贡献

本教程由社区贡献，不属于 Open WebUI 团队官方支持。它仅作为如何针对特定用例自定义 Open WebUI 的演示。想要贡献？请查看贡献教程。

方法 1：可流式传输 HTTP (推荐)

此方法直接连接到 Notion 托管的 MCP 端点 (https://mcp.notion.com/mcp)。它使用标准的 OAuth，并由 Open WebUI 原生支持，无需额外的容器。

首选方法

可流式传输 HTTP (Streamable HTTP) 因其简单性和增强的安全性而成为首选。它通过 Notion 官方的 OAuth 流程处理身份验证，这意味着您不需要手动管理密钥或集成令牌。

确保 OAuth 持久化

您必须在 Docker 设置中将 WEBUI_SECRET_KEY 环境变量设置为一个持久值。如果您不这样做，每次重启容器时，您的 Notion OAuth 会话都会失效，迫使您反复重新进行身份验证。

1. 配置工具

您可以通过导入下方的 JSON 配置来自动预填连接设置。

导航至 管理员面板 (Admin Panel) > 设置 (Settings) > 外部工具 (External Tools)。
点击 + (加号) 按钮添加新工具。
点击 导入 (Import) (位于弹窗右上角)。
粘贴以下 JSON 片段：

Notion 远程 MCP 配置
[
  {
    "type": "mcp",
    "url": "https://mcp.notion.com/mcp",
    "spec_type": "url",
    "spec": "",
    "path": "openapi.json",
    "auth_type": "oauth_2.1",
    "key": "",
    "info": {
      "id": "ntn",
      "name": "Notion",
      "description": "一个允许用户创建、组织和共享笔记、数据库及其他内容的笔记和协作平台。"
    }
  }
]

注册： 点击 Register Client 按钮 (位于 Auth 下拉菜单旁)。
点击 保存 (Save)。

Open WebUI 工具配置：显示已导入 JSON 并高亮 Register Client 按钮的外部工具弹窗。

2. 身份验证与授权访问

添加工具后，您必须进行身份验证以链接您特定的工作区。

打开任意聊天窗口。
点击聊天输入栏中的 + (加号) 按钮。
导航至 集成 (Integrations) > 工具 (Tools)。
将 Notion 开关切换为 开启 (ON)。

聊天界面切换：显示带有 '+' 菜单开启、选中 '集成' 并开启 'Notion' 工具的聊天输入栏。

授权： 您将被重定向到 "Connect with Notion MCP" 页面。
- 确保在下拉菜单中选择了正确的 工作区 (Workspace)。
- 点击 继续 (Continue)。

安全提示：频繁的重新验证

出于安全原因，Notion 的 OAuth 会话在一段不活动时间后或重启 Open WebUI 实例后可能会过期。如果发生这种情况，您将看到 Failed to connect to MCP server 'ntn' 错误。

这是 Notion 为了保持工作区安全而采取的 预期行为。要刷新会话，请重新执行上述步骤以再次完成 "Connect with Notion MCP" 授权流程。

Notion OAuth 页面：显示带有工作区下拉菜单选择的 'Connect with Notion MCP' 授权页面。

方法 2：通过 MCPO 自托管 (进阶)

此方法适用于希望使用 MCPO 在自己的基础设施中本地运行 MCP 服务器的高级用户。与可流式传输 HTTP 不同，此方法需要您手动管理自己的凭据。

Open WebUI 原生不支持 MCP 服务器的直接本地执行 (stdio)。要在您的基础设施中本地运行 Notion MCP 服务器（使用 Docker 或 Node.js），您必须使用 MCPO 作为连接桥梁。

前提条件

要使用此方法，您必须首先创建一个内部集成以获取 Secret Key。在进行此处的配置步骤之前，请先完成下方的 创建内部集成 部分。

1. 配置 MCPO

按照 MCPO 仓库中的安装说明使其运行。通过将 JSON 块添加到您的 mcpo-config.json 文件中，配置您的 MCPO 实例以使用下方的运行环境运行 Notion 服务器。

注意： 将 secret_YOUR_KEY_HERE 替换为从创建内部集成部分获得的密钥。

Node (npx)
Docker

此配置使用官方的 Node.js 包。

mcpo-config.json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ],
      "env": {
        "NOTION_TOKEN": "secret_YOUR_KEY_HERE"
      }
    }
  }
}

此配置使用官方 Docker 镜像。

mcpo-config.json
{
  "mcpServers": {
    "notion": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "NOTION_TOKEN",
        "mcp/notion"
      ],
      "env": {
        "NOTION_TOKEN": "secret_YOUR_KEY_HERE"
      }
    }
  }
}

2. 连接 Open WebUI

一旦 MCPO 运行并配置好 Notion：

导航至 管理员面板 (Admin Panel) > 设置 (Settings) > 外部工具 (External Tools)。
点击 + (加号) 按钮。
点击 导入 (Import) (位于弹窗右上角)。
粘贴以下 JSON 片段 (将 URL 更新为您的 MCPO 地址)：

MCPO 连接 JSON
[
  {
    "type": "openapi",
    "url": "http://<您的_MCPO_IP>:<端口>/notion",
    "spec_type": "url",
    "spec": "",
    "path": "openapi.json",
    "auth_type": "bearer",
    "key": "",
    "info": {
      "id": "notion-local",
      "name": "Notion (本地)",
      "description": "通过 MCPO 进行的本地 Notion 集成"
    }
  }
]

点击 保存 (Save)。

创建内部集成

方法 2 的必要步骤。在 Notion 中创建一个内部集成，确保您拥有所需的凭据和权限范围。

1. 创建集成

导航至 Notion 我的集成 (My Integrations)。
点击 + 新建集成 (+ New integration) 按钮。
填写必填字段：
- 集成名称 (Integration Name)： 起一个易于识别的名字 (例如 "Open WebUI MCP")。
- 关联工作区 (Associated workspace)： 选择您想要连接的特定工作区。
- 类型 (Type)： 选择 内部 (Internal)。
- Logo： 上传 Logo 是可选的，但有助于识别集成。
点击 提交 (Submit)。

重要：集成类型

您必须将集成类型选择为 内部 (Internal)。公共集成需要不同的 OAuth 流程，本指南不予涵盖。

Notion 集成设置表单：显示已填写名称、选中工作区并将 '类型' 设置为内部的 '新建集成' 页面。

2. 配置功能并复制 Secret

保存后，您将被引导至配置页面。

复制 Secret： 找到 内部集成令牌 (Internal Integration Secret) 字段。点击 显示 (Show) 并复制此密钥。您将在 MCPO 配置中用到它。
检查功能： 确保在 "功能 (Capabilities)" 部分选中了以下复选框：
- ✅ 读取内容 (Read content)
- ✅ 更新内容 (Update content)
- ✅ 插入内容 (Insert content)
- (可选) 读取包含电子邮件地址的用户信息。
如果您修改了任何功能，请点击 保存更改 (Save changes)。

安全提示：工作区数据风险

虽然 Notion MCP 服务器限制了 API 的范围 (例如，无法删除数据库)，但将您的工作区暴露给 LLM 仍存在 非零风险。

注重安全的用户 可以创建一个更安全的 只读 (Read-Only) 集成，只需取消勾选 更新内容 (Update content) 和 插入内容 (Insert content)。AI 将能够搜索并根据您的笔记回答问题，但在物理上无法修改或创建页面。

令牌安全

您的 内部集成令牌 (Internal Integration Secret) 允许访问您的 Notion 数据。请像对待密码一样对待它。不要分享它，也不要将其提交到公共代码库。

Notion 功能配置：显示已显示的内部集成令牌和选中的三个内容功能复选框。

3. 授权页面访问 (手动操作)

关键步骤：权限

默认情况下，您新创建的内部集成对您的工作区拥有 零访问权限。在您明确邀请它之前，它无法看到任何页面。如果您跳过此步骤，AI 将返回 "Object not found" 错误。

您可以集中授权访问，也可以逐页授权。

方法 A：集中授权访问 (推荐)

仍在 Notion 集成控制面板中：

点击 访问 (Access) 选项卡 (位于配置旁边)。
点击 编辑访问权限 (Edit access) 按钮。
将出现一个弹窗，允许您选择特定页面或 "选择所有 (Select all)" 顶层页面。
勾选您希望 AI 读取/编辑的页面，然后点击 保存 (Save)。

Notion 访问选项卡：显示 '管理页面访问' 弹窗，其中正在为集成选择特定的页面，如 '待办事项列表'。

方法 B：页面级授权访问

转到您希望 AI 访问的特定 Notion 页面或数据库。
点击页面右上角的 ... (三个点) 菜单。
选择 连接 (Connections) (位于 "添加连接" 部分)。
搜索您的集成名称 (例如 "Open WebUI MCP") 并点击 连接 (Connect)。
对于您希望 AI 能够搜索或编辑的每个根页面或数据库，您都必须重复此操作。

Notion 页面连接：显示一个 Notion 页面，其中开启了 '...' 菜单，选中了 '连接' 子菜单，并正在选择集成。

配置：始终开启 (可选)

默认情况下，用户必须在聊天菜单中将工具切换为 开启 (ON)。您可以配置特定的模型，使其在每次对话中默认启用 Notion 访问。

前往 工作区 (Workspace) > 模型 (Models)。
点击 铅笔图标 编辑模型。
向下滚动到 工具 (Tools) 部分。
勾选 Notion。
点击 保存并更新 (Save & Update)。

构建专门的 Notion 智能体 (可选)

为了获得最可靠的体验，我们建议创建一个专门的 "Notion 助手 (Notion Assistant)" 模型。这允许您提供专门的 系统提示词 (System Prompt)、有用的 知识库 (Knowledge Base) 以及快速上手的 提示词建议 (Prompt Suggestions)，教导模型如何导航 Notion 的结构。

第 1 步：为智能体创建知识库

首先，使用官方的 Notion MCP 文档创建一个知识库。这将帮助模型了解它自己的功能。

导航至知识库： 前往 工作区 (Workspace) > 知识库 (Knowledge)。
创建新知识库： 点击 + 新建知识 (New Knowledge) 按钮。
填写详细信息：
- 名称： Notion MCP Docs
- 描述： Notion MCP 工具的官方文档，用于提高智能体准确性。
点击 创建知识 (Create Knowledge)。

创建知识库表单：显示名称为 'Notion MCP Docs' 且带有相关描述的表单。

上传内容：
- 将来自 Notion MCP 文档的内容保存为 PDF 或 .txt 文件。
- 在您的新知识库中，点击 + 添加内容 (+ Add Content) 按钮并上传您保存的文件。

推荐：使用 Jina Reader 进行优化

为了获得最佳的 RAG 性能，我们建议将网页文档转换为整洁的 Markdown。您可以使用 Jina Reader (或托管的 https://r.jina.ai/ API) 来去除干扰信息，并专门为 LLM 格式化页面。

只需访问 https://r.jina.ai/https://developers.notion.com/docs/mcp-supported-tools，复制输出内容，并将其保存为 .md 文件进行上传。

知识库内容视图：显示 'Notion MCP Docs' 知识库，其中已成功上传文档文件。

第 2 步：创建自定义模型

现在，创建专门的智能体并关联您刚刚制作的知识库。

前往 工作区 (Workspace) > 模型 (Models) > 创建模型 (Create a Model)。
名称： Notion 助手
描述： 一个智能代理，使用 MCP 工具管理您的 Notion 工作区，实现搜索、读取和创建内容。
基础模型： 选择您喜欢的本地 LLM (例如 Llama 3.1)。
工具： 启用 Notion。
系统提示词： 粘贴以下优化后的提示词：

点击查看优化后的系统提示词

您是 Notion 工作区管理器，一个通过模型上下文协议 (MCP) 直接连接到用户 Notion 工作区的智能代理。您的目标是帮助用户在他们的个人知识库中组织、检索和生成内容。

### 关键操作规则：

1. **搜索是强制性的：**
   - 如果没有唯一的 ID 或 URL，您无法与页面或数据库进行交互。
   - 如果用户通过名称引用页面 (例如，“将此添加到我的待办事项列表”)，您必须首先运行 `notion-search` 以找到正确的页面并获取其 ID 或 URL。
   - 永远不要猜测页面 ID。
   - 如果搜索返回多个结果 (例如，两个名为“会议记录”的页面)，请在继续之前询问用户明确使用哪一个。

2. **先读取再回答：**
   - 如果用户询问有关其数据的问题 (例如，“项目 Alpha 的状态是什么？”)，不要根据您的内部训练数据回答。
   - 首先运行 `notion_search` 查找相关页面，然后运行 `notion-read-page` 获取内容，最后*严格*根据工具输出进行回答。
   - 注意：页面内容以 Markdown 格式返回给您。请在回答中保留此结构。

3. **创建协议：**
   - 当被要求创建页面 (`notion-create-page`) 时，您必须确定父页面 ID。
   - 如果用户未指定位置，请搜索逻辑上的父页面 (如“仪表板”、“项目”或“笔记”)，或者询问用户放置位置。

4. **内容格式化：**
   - 当追加内容 (`notion-append-block`) 或创建页面时，请使用整洁的 Markdown。
   - 使用标题、列表和复选框来组织复杂信息，以有效地利用 Notion 的块结构。

### 错误处理：
- 如果工具返回“Object not found”或空的搜索结果，请告知用户：“我无法看到该页面。请确保您已通过 Notion 中的 '...' 菜单 > 连接 (Connections) 将其连接到 Open WebUI 集成。”

### 行为准则：
- 简洁明了，以行动为导向。
- 完成操作后进行确认 (例如，“✅ 我已将该任务添加到您的‘任务’数据库中。”)。
- 如果您正在分析来自 Notion 页面的大量文本，请提供结构化摘要，除非被要求提供特定细节。

关联知识库：
- 在 知识库 (Knowledge) 部分，点击 选择知识 (Select Knowledge)。
- 在出现的弹窗中，找到并选择您在第 1 步中创建的 Notion MCP Docs 知识库。

性能调优

虽然知识库有助于模型理解 Notion 的功能，但注入大量文档有时会干扰较小模型的工具调用 (导致上下文过载)。

如果您注意到模型无法正确调用工具或出现参数幻觉，请 取消关联知识库，并仅依靠上面提供的系统提示词。

添加提示词建议：

在 提示词 (Prompts) 部分，点击 + 按钮添加一些有用的起始提示词。

#	标题	副标题	提示词
1	搜索我的工作区	寻找特定页面	在 Notion 中搜索我的 '项目路线图' 页面。
2	总结页面	在找到页面之后	首先搜索 '入职指南' 页面，然后读取其内容并给我一个总结。
3	添加新任务	到我的主待办事项列表	找到我的 '待办事项列表' 页面并添加一个新任务：“跟进设计团队。”

模型提示词配置：显示填写了示例的 '默认提示词建议' 部分。

最后，保存并更新 (Save & Update) 模型。

模型创建界面：显示名称为 'Notion 助手'、包含描述并填写了 Notion 系统提示词的模型设置。

支持的工具

工作流程最佳实践

LLM 无法像人类那样“浏览” Notion。对于大多数操作，模型首先需要知道 页面 ID 或 URL。在要求模型读取或修改页面之前，请务必先要求它搜索页面。

此集成支持一系列用于搜索、读取、创建和更新 Notion 页面及数据库的工具。

有关可用工具的完整列表、它们的描述以及具体的用法示例，请参阅 官方 Notion MCP 文档。

速率限制

Notion MCP 的使用受标准 API 请求限制的约束，所有工具调用的总和。

常规限制： 平均 每分钟 180 次请求 (每秒 3 次请求)。
搜索专用限制： 每分钟 30 次请求。

速率限制

如果您遇到速率限制错误，请提示您的模型减少并行搜索或操作的数量。例如，不要一次性“搜索 A、B 和 C”，尝试按顺序请求它们。

故障排除

连接错误

`Failed to connect to MCP server 'ntn'`

MCP 连接错误：在聊天中显示红色的错误消息 'Failed to connect to MCP server 'ntn'。

原因： 这通常表示您与 Notion 的 OAuth 会话已过期，或者令牌需要刷新。这通常发生在重启 Open WebUI 或一段不活动时间之后。
解决方法：
1. 打开任意聊天。
2. 点击 + (加号) 按钮 > 集成 (Integrations) > 工具 (Tools)。
3. 将 Notion 开关切换为 开启 (ON)。
4. 这将触发重定向到 Notion 的授权页面，以再次完成 "Connect with Notion MCP" 授权流程。
5. 授权成功后，连接将在所有聊天中再次生效，包括默认启用该工具的模型。

方法 1：可流式传输 HTTP (推荐)​

1. 配置工具​

2. 身份验证与授权访问​

方法 2：通过 MCPO 自托管 (进阶)​

1. 配置 MCPO​

2. 连接 Open WebUI​

创建内部集成​

1. 创建集成​

2. 配置功能并复制 Secret​

3. 授权页面访问 (手动操作)​

方法 A：集中授权访问 (推荐)​

方法 B：页面级授权访问​

配置：始终开启 (可选)​

构建专门的 Notion 智能体 (可选)​

第 1 步：为智能体创建知识库​

第 2 步：创建自定义模型​

支持的工具​

速率限制​

故障排除​

连接错误​

Failed to connect to MCP server 'ntn'​

OAuth callback failed: mismatching_state​

方法 1：可流式传输 HTTP (推荐)

1. 配置工具

2. 身份验证与授权访问

方法 2：通过 MCPO 自托管 (进阶)

1. 配置 MCPO

2. 连接 Open WebUI

创建内部集成

1. 创建集成

2. 配置功能并复制 Secret

3. 授权页面访问 (手动操作)

方法 A：集中授权访问 (推荐)

方法 B：页面级授权访问

配置：始终开启 (可选)

构建专门的 Notion 智能体 (可选)

第 1 步：为智能体创建知识库

第 2 步：创建自定义模型

支持的工具

速率限制

故障排除

连接错误

`Failed to connect to MCP server 'ntn'`

`OAuth callback failed: mismatching_state`