notion-full-mcp

Name: notion-full-mcp
Author: cphoskins

本地服务

github.com/cphoskins生产力03 天前更新

代码仓库

关于 notion-full-mcp

notion-full-mcp 是面向 MCP 客户端的 Notion 服务，提供页面读取、编辑及恢复等操作。它涵盖表格和文件处理，并通过工具注释标明操作是否只读、添加或具有破坏性。

主要功能

01递归读取页面内容
02编辑区块与表格单元格
03快照及失败回滚恢复
04上传、下载 Notion 文件
05移动、复制及恢复页面

适用场景

01检查页面及嵌套内容
02修改页面文字或表格行
03备份页面并恢复内容
04将文件插入 Notion 页面

MCP 相关

作为 MCP 服务向客户端提供 33 种 Notion 页面、区块、数据库、评论、用户及文件操作工具。工具注释标识只读、添加或破坏性操作。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cphoskins-notion-full": {
      "command": "uvx",
      "args": [
        "notion-full-mcp"
      ],
      "env": {
        "NOTION_API_TOKEN": "<NOTION_API_TOKEN>",
        "NOTION_MCP_FILE_ROOT": "<NOTION_MCP_FILE_ROOT>"
      }
    }
  }
}

启动命令uvx notion-full-mcp

需要配置的环境变量

NOTION_API_TOKEN密钥Your Notion integration API token (starts with ntn_)

NOTION_MCP_FILE_ROOTOptional directory that uploads, downloads and snapshots are confined to

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypinotion-full-mcp0.5.1stdio

工具

收录的工具列表 · 更新于 2 天前

参数	类型	必填	说明
query	string	是
max_results	integer	否

详细介绍

notion-full-mcp

Notion MCP 服务，支持深度读取页面、精准编辑块、安全快照与还原、上传文件（托管在 Notion 上的图片和 PDF）、操作表格行、移动和复制页面，以及从回收站还原页面。

v0.5.1 新增内容

工具注释。 每个工具都会声明自身是只读、增量式还是破坏性操作，因此 MCP 客户端无需询问即可决定运行哪些工具。
MCP Registry。 该服务已发布到官方 MCP Registry，名称为 io.github.cphoskins/notion-full-mcp。

v0.5.0 新增内容

还原后页面顺序不变。 页面上仍存在的子页面、内嵌数据库和 Notion 托管文件会保持原样，还原的内容会按照快照中的顺序写入它们周围。
还原时会从回收站恢复项目。 快照之后删除的子页面、数据库或托管文件会从 Notion 回收站恢复，并保留其 ID、评论和历史记录。
快照可以包含文件。 使用 include_files 调用 snapshot_page 时，会将 Notion 托管的图片和文件下载到 JSON 文件旁边；还原时会在原位置重新上传这些文件。
修复：在某个块之后插入超过 100 个块时，现在会保持它们的顺序。

v0.4.0 新增内容

还原不再会丢失内容。 restore_page_from_snapshot 会先写入快照，只有成功后才删除旧块。还原失败时会回滚，页面保持原样。子页面、内嵌数据库和 Notion 托管文件绝不会被删除。
move_page 现已可用。 它使用 Notion 的移动端点，因此页面会保留其 ID、内容、评论和子页面。
copy_page_to_parent 会报告无法复制的内容。 无法复制的块类型会列在 skipped 中，并且只有全部内容都复制成功后，才会归档原页面。
处理大型和深层内容。 嵌套超过两层的列表、超过 100 行的表格以及超过 2,000 个字符的文本，会自动拆分到多个请求中。
编辑后仍会保留提及和公式。 查找/替换、还原和复制都会保留用户、页面、数据库和日期提及，以及行内公式。
改进错误提示和速率限制处理。 错误会包含 Notion 自身的代码和消息。遇到速率限制时，会根据 Retry-After 重试请求。
数据库行现在包含标题。 搜索、页面信息和创建操作都会返回标题，无论标题列叫什么。
支持更多块类型。 公式、书签、嵌入内容和外部托管的媒体块都支持通过快照/还原和复制进行往返处理。
可选的文件边界。 设置 NOTION_MCP_FILE_ROOT，即可将上传、下载和快照限制在一个目录中。

v0.3.0 新增内容

从回收站还原页面。 restore_page 会通过发送 archived=False 显式取消页面归档。这是页面上 delete_block 的对应操作，也绕过了 update_page 中阻止设置 archived=False 的安全保护。恢复父页面时，会自动恢复级联归档的子页面。
跨父级破坏性复制页面。 copy_page_to_parent 是 Notion 公共 API 不支持更改父级时的替代方案。它会在目标父级下重新创建页面，保留相同的标题、图标和内容，然后归档原页面。支持段落、标题、列表、表格、分隔线、代码块以及图片/文件块。如果源页面包含嵌套的 child_page 后代，则拒绝运行（请手动复制这些内容）。
move_page 不再假装可以移动页面。 Notion 的 PATCH /pages/{id} 端点会静默忽略父级更改，因此该工具会改为返回错误。（v0.4.0 实现了真正的移动。）

v0.2.0 版本更新内容

Notion 文件上传。 将图片和文件直接上传到 Notion 自己的工作区存储，而不再依赖外部图床。支持 PNG、JPEG、SVG、GIF、PDF 以及 Notion 支持的其他附件类型。
图片块辅助工具。 upload_image_as_block 可在一次调用中上传文件并将其插入指定位置。replace_image_block 可替换现有图片的内容，同时保留其在父级中的位置。download_image_block 可将任意图片块的文件下载到磁盘。
表格行操作。 insert_table_row 可向现有表格添加行，并自动验证宽度。update_table_cell 可替换单个单元格的文本。小幅编辑不必再重建整张表格。

安装

pip install notion-full-mcp
# or
uv pip install notion-full-mcp

快速开始

export NOTION_API_TOKEN="your-token-here"
notion-mcp

Claude Code 集成

在 ~/.claude.json 的 mcpServers 下添加：

{
  "notion-full": {
    "type": "stdio",
    "command": "uvx",
    "args": ["notion-full-mcp"],
    "env": {
      "NOTION_API_TOKEN": "your-token-here"
    }
  }
}

或用于本地开发：

{
  "notion-full": {
    "type": "stdio",
    "command": "uv",
    "args": ["run", "--directory", "/path/to/notion-full-mcp", "notion-mcp"],
    "env": {
      "NOTION_API_TOKEN": "your-token-here"
    }
  }
}

工具（33 个）

搜索与页面

工具	描述
`search_pages`	按标题搜索页面
`search`	搜索页面和／或数据库
`get_page_info`	获取页面元数据（标题、父级、日期、URL）
`create_page`	在父页面或数据库下创建新页面
`update_page`	更新页面的标题、图标或归档状态
`move_page`	将页面移至新的父页面下，同时保留其 ID 和内容
`restore_page`	从回收站恢复页面（及其级联归档的子页面）
`copy_page_to_parent`	在新的父页面或数据库下重新创建页面。仅当所有块均已复制时，才归档原页面

阅读

工具	描述
`read_page_deep`	读取页面及其所有嵌套子项（递归）
`list_block_children`	列出块或页面的直接子项
`get_block`	按 ID 获取单个块

编辑

工具	描述
`update_block_text`	替换块中的所有文本
`find_replace_in_block`	查找并替换文本，同时保留格式
`update_block_rich_text`	使用完整的富文本规范更新

插入

工具	描述
`insert_text_after`	在指定块后插入文本块（段落、heading_1/2/3、项目符号列表项、编号列表项、引用、标注、折叠块、待办事项、代码、分隔线）
`insert_blocks_after`	在指定块后插入多个块
`append_blocks_to_page`	将块追加到页面末尾

删除

工具	描述
`delete_block`	按 ID 删除块

工具	描述
`create_comment`	为页面添加评论
`list_comments`	列出页面或块上的所有评论

数据库

工具	描述
`get_database`	获取数据库元数据和架构
`query_database`	使用筛选条件和排序方式查询数据库

用户

工具	描述
`get_self`	获取当前已通过身份验证的用户／机器人
`list_users`	列出工作区中的所有用户

快照／恢复

工具	描述
`snapshot_page`	将完整页面结构保存为 JSON。`include_files` 还会保存托管在 Notion 上的图片和文件
`restore_page_from_snapshot`	从快照恢复页面内容。先写入，失败时回滚；保留子页面和数据库原位，恢复从回收站删除的项目，并重新上传已保存的文件

媒体与文件

工具	描述
`upload_file`	将文件上传到 Notion 自有的工作区存储（返回 `file_upload_id`）
`upload_image_as_block`	上传图片，并一步将其插入为新的图片块（插入到某个块之后或追加到页面末尾）
`replace_image_block`	用新上传的文件替换现有图片块，并保留其位置
`download_image_block`	将图片块中的图片文件下载到磁盘——适用于外部 URL、Notion 托管文件和 `file_upload` 引用
`upload_file_as_block`	上传任意文件（PDF、附件），并将其插入为文件块

表格

工具	描述
`insert_table_row`	在现有表格中插入新行，并自动验证宽度
`update_table_cell`	替换表格行中单个单元格的文本

工具注释

每个工具都带有 MCP 注释，客户端可据此判断哪些操作可以安全执行，而无需询问：

**只读（11 个）：**搜索、页面和块读取、评论列表、数据库读取和用户查询。
**只添加、不丢失内容（13 个）：**插入、追加、上传、创建页面和评论、move_page、restore_page，以及两个用于写入本地文件的工具（snapshot_page、download_image_block）。
标记为破坏性操作（9 个）：update_block_text、update_block_rich_text、find_replace_in_block、update_table_cell、replace_image_block、delete_block、update_page、copy_page_to_parent 和 restore_page_from_snapshot。这些操作会覆盖、删除或归档现有内容。

块支持与限制

**可往返处理（快照/恢复和复制）：**段落、标题（包括可切换标题）、项目符号列表和编号列表、待办事项、引用、标注、切换块、代码、分隔线、表格、分栏、目录、公式、书签、嵌入内容，以及外部托管的图片、文件、视频、PDF 和音频块。
**无法从头重建：**子页面、内联数据库和同步块。复制操作会将它们报告为 skipped。
恢复这些块及 Notion 托管文件时：
- **仍在页面上：**保持原样，恢复的内容会按照快照顺序写入它们周围（preserved）。如果某个块被拖动到快照顺序之外，它会留在原处（out_of_order）。
- **文件随快照保存：**重新上传并在原处重建（uploaded）。超过 20 MB 或超过工作区上传限制的文件不会上传。
- **在 Notion 回收站中：**以同一个块恢复（restored_from_trash）。Notion 会将其放回页面末尾，因此，若某个仍在页面上的块在快照中排在它后面，该块最终会位于它上方，并被报告为 out_of_order。
- **已从回收站永久删除，且没有保存的文件：**无法恢复（skipped）。
- **为何不会移动 out_of_order 块（这是有意设计的）：**Notion API 无法重新定位块。移动子页面或数据库的唯一方法是将其移至回收站再恢复；这样会将其放到页面末尾，而且如果中途失败，它会留在回收站中。恢复操作绝不会删除无法重建的内容，因此会报告该块，并留给你手动拖动到正确位置。
**快照：**将子页面和内联数据库记录为块，但不包含其自身内容。只有使用 include_files 时才会保存 Notion 托管文件；否则，快照只保留有效期不到一小时的链接。
查询：query_database 最多返回 500 行；若匹配结果更多，则会设置 truncated。
**查找/替换：**只会在单个格式片段内匹配。跨越加粗或链接边界的短语会被报告为未找到。
**API 版本：**请求使用 Notion API 版本 2022-06-28。

配置

变量	必需	用途
`NOTION_API_TOKEN`	是	集成密钥
`NOTION_MCP_FILE_ROOT`	否	设置后，上传、下载和快照文件必须位于此目录中

开发

uv run pytest --cov=notion_mcp      # unit tests, no credentials needed

实时检查会在真实工作区中运行每个工具。它会在你指定的父级页面下使用一个临时页面，之后将其移至回收站：

export NOTION_API_TOKEN="your-token-here"
export NOTION_TEST_PARENT_PAGE="page-id-shared-with-the-integration"
uv run python scripts/live_check.py

Notion API 令牌

前往 https://www.notion.so/my-integrations
创建一个新的集成
复制令牌（以 ntn_ 开头）
将你想要访问的页面／数据库共享给该集成

许可证

MIT

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

notion-full-mcp

关于 notion-full-mcp

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

notion-full-mcp

v0.5.1 新增内容

v0.5.0 新增内容

v0.4.0 新增内容

v0.3.0 新增内容

v0.2.0 版本更新内容

安装

快速开始

Claude Code 集成

工具（33 个）

搜索与页面

阅读

编辑

插入

删除

评论

数据库

用户

快照／恢复

媒体与文件

表格

工具注释

块支持与限制

配置

开发

Notion API 令牌

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？