Notion MCP Server - 官方 Notion 工作空间 AI 集成

Posted on 十月 11, 2025

Notion MCP Server - 官方 Notion 工作空间 AI 集成

官方实现 | Stars: 3200 | TypeScript | MIT

概述

Notion MCP Server 是 Notion 官方提供的 Model Context Protocol 实现，为 AI 助手提供完整的 Notion API 访问能力。它支持页面创建、数据库查询、内容更新、评论管理等核心功能，让 AI 工具能够直接与 Notion 工作空间交互，实现智能化的知识管理和团队协作。

该服务器提供了两种部署方式：官方托管版本（mcp.notion.com）和自托管版本，支持 Streamable HTTP、SSE、STDIO 三种传输协议。特别适合需要 AI 辅助的知识库管理、文档创作、项目管理等场景。作为 Notion 官方维护的项目，它具有长期稳定性和完整的功能支持。

核心特性

✅ Notion 官方实现，长期稳定支持和持续更新
🌐 托管服务可用，开箱即用的 mcp.notion.com
🛠️ 12+ 核心工具，涵盖搜索、创建、更新、移动、复制等操作
🔐 OAuth 认证，托管版本支持一键授权
🎯 双部署模式，托管版本和自托管版本灵活选择
📡 三种传输协议，Streamable HTTP、SSE、STDIO 全面支持
🔒 安全权限控制，支持只读模式和细粒度权限管理
⚡ 优化性能，Token 消费优化，成本更低
🐳 Docker 支持，容器化部署方案
📚 完整 API 覆盖，支持页面、数据库、块、评论等所有核心功能

工具列表

1. notion-search

功能：在 Notion 工作空间中搜索页面、数据库和内容

参数：

query (string, 必需) - 搜索查询文本
filter (object, 可选) - 搜索过滤条件（如页面类型、最后编辑时间等）

示例：

1
2
3

{
  "query": "budget approval process"
}

使用场景：

快速查找相关文档和页面
基于关键词的内容检索
查找历史会议记录和项目文档

2. notion-fetch

功能：通过 URL 或 ID 获取 Notion 页面或数据库的完整内容

参数：

url (string, 必需) - Notion 页面或数据库的 URL

示例：

1
2
3

{
  "url": "https://www.notion.so/my-page-1a6b35e6e67f802fa7e1d27686f017f2"
}

使用场景：

读取页面内容供 AI 分析
获取数据库结构和数据
提取特定页面的详细信息

3. notion-create-pages

功能：创建一个或多个 Notion 页面，支持指定属性和内容

参数：

parent (object, 必需) - 父页面或数据库的 ID 或 URL
title (string, 必需) - 页面标题
properties (object, 可选) - 页面属性（如标签、状态等）
content (array, 可选) - 页面内容块（文本、标题、列表等）

示例：

{
  "parent": {"page_id": "abc123"},
  "title": "Project Kickoff Meeting",
  "content": [
    {"type": "heading_2", "text": "Agenda"},
    {"type": "bulleted_list_item", "text": "Introduction"},
    {"type": "bulleted_list_item", "text": "Project Overview"}
  ]
}

使用场景：

AI 自动生成会议纪要
批量创建标准化文档
自动化报告生成

4. notion-update-page

功能：更新现有页面的属性或内容

参数：

page_id (string, 必需) - 要更新的页面 ID
properties (object, 可选) - 要更新的页面属性
content (array, 可选) - 要追加或更新的内容块

示例：

{
  "page_id": "def456",
  "properties": {
    "Status": {"select": {"name": "Complete"}}
  }
}

使用场景：

更新任务状态
追加页面内容
修改页面属性和标签

5. notion-move-pages

功能：将页面或数据库移动到新的父页面下

参数：

page_id (string, 必需) - 要移动的页面 ID
new_parent_id (string, 必需) - 新父页面的 ID

示例：

{
  "page_id": "ghi789",
  "new_parent_id": "team-meetings-folder"
}

使用场景：

重新组织文档结构
归档完成的项目
整理分类页面

6. notion-duplicate-page

功能：复制 Notion 页面及其所有内容

参数：

page_id (string, 必需) - 要复制的页面 ID
new_title (string, 可选) - 新页面的标题

示例：

{
  "page_id": "template-123",
  "new_title": "Q3 2025 Initiative"
}

使用场景：

使用模板创建新项目
复制标准化文档
快速创建相似内容

7. notion-create-database

功能：创建新的 Notion 数据库，支持自定义属性和视图

参数：

parent (object, 必需) - 父页面或数据库的 ID
title (string, 必需) - 数据库标题
properties (object, 必需) - 数据库属性定义（列类型、选项等）

示例：

{
  "parent": {"page_id": "workspace-root"},
  "title": "Customer Feedback Tracker",
  "properties": {
    "Name": {"title": {}},
    "Status": {"select": {"options": [
      {"name": "New", "color": "blue"},
      {"name": "In Progress", "color": "yellow"},
      {"name": "Done", "color": "green"}
    ]}},
    "Priority": {"select": {"options": [
      {"name": "High", "color": "red"},
      {"name": "Medium", "color": "yellow"},
      {"name": "Low", "color": "gray"}
    ]}}
  }
}

使用场景：

创建项目跟踪数据库
建立客户反馈系统
构建任务管理看板

8. notion-update-database

功能：更新数据库的属性、名称或配置

参数：

database_id (string, 必需) - 数据库 ID
title (string, 可选) - 新的数据库标题
properties (object, 可选) - 要添加或更新的属性

示例：

{
  "database_id": "db-456",
  "properties": {
    "Completion": {"number": {"format": "percent"}}
  }
}

使用场景：

添加新的数据库列
修改列的类型或选项
重命名数据库

9. notion-create-comment

功能：在页面上添加评论

参数：

page_id (string, 必需) - 要评论的页面 ID
comment (string, 必需) - 评论内容

示例：

{
  "page_id": "design-proposal-789",
  "comment": "Looks great! Let's proceed with this approach. @john please review the technical feasibility."
}

使用场景：

AI 辅助的文档审阅
自动添加反馈和建议
团队协作和讨论

10. notion-get-comments

功能：获取页面上的所有评论

参数：

page_id (string, 必需) - 页面 ID

示例：

1
2
3

{
  "page_id": "requirements-page-456"
}

使用场景：

提取讨论历史
分析团队反馈
汇总评审意见

11. notion-get-teams

功能：获取工作空间中的团队列表

参数：

query (string, 可选) - 按名称搜索团队

示例：

1
2
3

{
  "query": "Engineering"
}

使用场景：

查询团队信息
权限管理
团队分析

12. notion-get-users

功能：获取工作空间用户信息

参数：

user_id (string, 可选) - 特定用户的 ID（留空获取所有用户）

示例：

{}

使用场景：

获取团队成员列表
用户权限查询
协作者信息

配置方式

托管版本配置（推荐）

Streamable HTTP（推荐）

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "Notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

SSE（Server-Sent Events）

{
  "mcpServers": {
    "Notion": {
      "type": "sse",
      "url": "https://mcp.notion.com/sse"
    }
  }
}

授权流程：

打开 Notion 设置
进入 Settings → Connections → Notion MCP
选择你的 AI 工具（如 Claude Desktop、Cursor）
完成 OAuth 授权
选择要授权访问的页面和数据库

自托管版本配置

环境变量

1 2	# Notion Integration Token（必需） NOTION_TOKEN=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Claude Desktop 配置

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/mcp-server-notion"],
      "env": {
        "NOTION_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Docker 部署

1
2
3

docker run -p 3000:3000 \
  -e NOTION_TOKEN="secret_your_token_here" \
  ghcr.io/makenotion/notion-mcp-server

本地运行

# 设置环境变量
export NOTION_TOKEN="secret_your_token_here"

# 运行服务器
npx @notionhq/mcp-server-notion

从源码构建

git clone https://github.com/makenotion/notion-mcp-server.git
cd notion-mcp-server
npm install
npm run build
npx -y --prefix . @notionhq/notion-mcp-server

创建 Notion Integration（自托管必需）

访问 https://www.notion.so/my-integrations
点击 “New integration”
填写集成信息：
- Name: 你的集成名称（如 “My AI Assistant”）
- Logo: 可选
- Associated workspace: 选择工作空间
配置权限（Capabilities）：
- ✅ Read content
- ✅ Update content
- ✅ Insert content
- ✅ Read comments
- ✅ Create comments
- ✅ Read user information
复制 “Internal Integration Token”
在需要访问的页面中：
- 点击页面右上角 “…”
- 选择 “Connect to”
- 选择你创建的集成

使用场景

1. AI 辅助笔记和文档创作

自动生成和整理 Notion 页面，提高文档创作效率。

示例流程：

AI 提取会议录音或对话内容
使用 notion-create-pages 创建会议纪要页面
使用 notion-update-page 追加行动项和决策
使用 notion-create-comment 添加后续建议

实际应用：

自动生成会议纪要
AI 辅助写作和大纲生成
内容摘要和重点提取

2. 知识库管理和检索

AI 驱动的知识组织和智能搜索。

示例流程：

用户提问：”我们上季度的产品发布流程是什么？”
使用 notion-search 搜索相关文档
使用 notion-fetch 获取详细内容
AI 整合信息并提供答案

实际应用：

企业知识库问答
文档智能检索
历史信息查询

3. 项目管理和任务跟踪

智能任务分配和进度管理。

示例流程：

使用 notion-create-database 创建项目跟踪数据库
使用 notion-create-pages 批量创建任务
使用 notion-update-page 更新任务状态
使用 notion-get-comments 提取团队反馈

实际应用：

敏捷项目管理
任务自动分配
进度智能跟踪

4. 团队协作和反馈管理

AI 辅助的团队沟通和文档审阅。

示例流程：

使用 notion-fetch 获取设计文档
AI 分析并生成审阅意见
使用 notion-create-comment 添加反馈
使用 notion-get-comments 汇总团队意见

实际应用：

设计评审自动化
文档质量检查
团队反馈收集

5. 模板复用和标准化

快速复制和创建标准化文档。

示例流程：

使用 notion-duplicate-page 复制项目模板
使用 notion-update-page 自定义新项目信息
使用 notion-move-pages 组织到正确的文件夹

实际应用：

项目启动自动化
标准文档生成
流程模板应用

6. 数据分析和报告生成

从 Notion 数据库提取和分析数据。

示例流程：

使用 notion-fetch 获取数据库内容
AI 分析数据并生成洞察
使用 notion-create-pages 创建分析报告
使用 notion-update-database 添加新的分析字段

实际应用：

客户反馈分析
项目绩效报告
数据驱动决策

技术架构

部署架构

托管版本:
用户 → AI 客户端 → mcp.notion.com → Notion API
                     ↑
                 OAuth 认证

自托管版本:
用户 → AI 客户端 → 本地 MCP Server → Notion API
                     ↑
                 Integration Token

传输协议对比

协议	优势	适用场景	推荐度
Streamable HTTP	高性能、实时流式传输	Web 应用、远程访问	⭐⭐⭐⭐⭐
SSE	服务器推送、单向流	实时通知、日志流	⭐⭐⭐⭐
STDIO	简单、本地通信	CLI 工具、本地应用	⭐⭐⭐

支持的 MCP 客户端

Claude Desktop - 官方支持，完整功能
Cursor - 代码编辑器集成
Zed - 现代编辑器
VS Code (Cline) - 通过 Cline 扩展
任何支持 MCP 的客户端 - 遵循 MCP 协议即可

与其他 MCP 服务器对比

特性	Notion MCP	Linear MCP	Slack MCP
官方维护	✅ 是	✅ 是	❌ 否
托管服务	✅ 提供	❌ 无	❌ 无
工具数量	12+	8+	6+
文档管理	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐
项目管理	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐
团队协作	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
数据库功能	⭐⭐⭐⭐⭐	⭐⭐⭐	❌ 无

最佳实践

1. 权限管理

// 推荐：只读集成配置
Capabilities:
  - Read content ✅
  - Read comments ✅
  - Read user information ✅
  - Update content ❌ (如果只需要读取)
  - Insert content ❌

2. 页面连接管理

// 最佳实践：按项目组织连接
项目 A 页面 → 连接到 "Project A Integration"
项目 B 页面 → 连接到 "Project B Integration"
共享知识库 → 连接到 "Knowledge Base Integration"

3. 批量操作优化

// 避免频繁调用
for (let i = 0; i < 100; i++) {
  await notionCreatePage(); // ❌ 慢
}

// 推荐：使用批量创建
await notionCreatePages([...pages]); // ✅ 快

4. 错误处理

// 处理 API 限流
try {
  await notionSearch({ query: "test" });
} catch (error) {
  if (error.code === "rate_limited") {
    // 等待并重试
    await wait(60000);
    retry();
  }
}

5. 内容结构化

// 良好的页面结构
{
  "title": "项目计划",
  "content": [
    {"type": "heading_1", "text": "概述"},
    {"type": "paragraph", "text": "..."},
    {"type": "heading_2", "text": "目标"},
    {"type": "bulleted_list_item", "text": "目标 1"},
    {"type": "heading_2", "text": "时间线"},
    {"type": "table", "rows": [...]}
  ]
}

常见问题

Q: 托管版本和自托管版本有什么区别？

托管版本：

✅ 无需本地安装
✅ 自动更新
✅ OAuth 认证
✅ 更简单的配置
❌ 需要外网访问

自托管版本：

✅ 完全控制
✅ 本地运行
✅ 自定义扩展
❌ 需要维护
❌ 需要创建集成

Q: 如何处理 API 限流？

Notion API 限制：

平均 180 请求/分钟（3 请求/秒）
某些工具有更严格的限制

建议：

使用批量操作减少请求次数
实现请求队列和重试机制
监控 API 使用情况

Q: 支持哪些内容类型？

支持的 Notion 块类型：

文本块（段落、标题、列表）
媒体块（图片、视频、文件）
数据块（表格、数据库、代码）
嵌入块（链接、书签）
高级块（切换列表、列布局）

Q: 如何迁移现有数据？

// 示例：批量导入页面
const pages = await loadExistingData();

for (const page of pages) {
  await notionCreatePages({
    parent: { page_id: "target-parent" },
    title: page.title,
    content: convertToNotionBlocks(page.content)
  });
}

Q: 如何调试集成问题？

检查集成配置：
- 确认 Token 正确
- 验证权限设置
检查页面连接：
- 页面是否已连接到集成
- 连接范围是否足够

查看错误日志：

1 2	# 自托管版本 npx @notionhq/mcp-server-notion --debug

测试 API 访问：

1
2
3

curl -X GET https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28"

Q: 性能如何优化？

使用托管版本：自动优化和缓存
批量操作：减少 API 调用次数
本地缓存：缓存常用数据
异步处理：并行执行独立操作

评分详情

维度	评分	说明
功能性	4.9/5.0	完整的 Notion API 覆盖，功能全面
文档质量	4.8/5.0	官方文档详细，示例丰富
社区活跃度	4.7/5.0	Notion 官方维护，社区活跃
维护状态	4.9/5.0	持续更新，响应及时
代码质量	4.6/5.0	TypeScript 实现，代码规范
综合评分	4.7/5.0	优秀的官方 MCP 实现

总结

Notion MCP Server 是连接 AI 助手与 Notion 工作空间的最佳选择。它由 Notion 官方团队维护，提供了完整的 API 功能覆盖和灵活的部署选项。

推荐指数: ⭐⭐⭐⭐⭐ (5/5)

适合你的情况：

✅ 使用 Notion 作为主要知识管理工具
✅ 需要 AI 辅助的文档创作和管理
✅ 团队协作和项目管理场景
✅ 需要自动化知识库维护
✅ 要求官方支持和长期稳定性

不适合的情况：

❌ 不使用 Notion
❌ 只需要简单的笔记功能
❌ 无法访问外网（托管版本）
❌ 需要高频率的 API 调用（受限流限制）

Notion MCP Server - 官方 Notion 工作空间 AI 集成

概述

核心特性

工具列表

1. notion-search

2. notion-fetch

3. notion-create-pages

4. notion-update-page

5. notion-move-pages

6. notion-duplicate-page

7. notion-create-database

8. notion-update-database

9. notion-create-comment

10. notion-get-comments

11. notion-get-teams

12. notion-get-users

配置方式

托管版本配置（推荐）

Streamable HTTP（推荐）

SSE（Server-Sent Events）

自托管版本配置

环境变量

Claude Desktop 配置

Docker 部署

本地运行

从源码构建

创建 Notion Integration（自托管必需）

使用场景

1. AI 辅助笔记和文档创作

2. 知识库管理和检索

3. 项目管理和任务跟踪

4. 团队协作和反馈管理

5. 模板复用和标准化

6. 数据分析和报告生成

技术架构

部署架构

传输协议对比

支持的 MCP 客户端

与其他 MCP 服务器对比

最佳实践

1. 权限管理

2. 页面连接管理

3. 批量操作优化

4. 错误处理

5. 内容结构化

常见问题

Q: 托管版本和自托管版本有什么区别？

Q: 如何处理 API 限流？

Q: 支持哪些内容类型？

Q: 如何迁移现有数据？

Q: 如何调试集成问题？

Q: 性能如何优化？

评分详情

总结

相关资源