Easy Notion MCP
Easy Notion MCP
以 Markdown 为先的 MCP 服务器,将 AI 智能体连接到 Notion。 智能体编写 markdown —— easy-notion-mcp 将其转换为 Notion 的 block API,并再转换回来。
43 个工具 · 24 种 block 类型 · 相比官方 Notion MCP 响应 token 减少 ~6–7× · 有文档记录的往返支持
npx easy-notion-mcp查看实际效果 → 完全通过 easy-notion-mcp 创建和管理的实时 Notion 页面。

目录: easy-notion-mcp 与其他 Notion MCP 服务器相比如何? · 如何设置 easy-notion-mcp? · 用于低上下文 Notion 访问的 CLI 配置文件 · 配置 · 为什么选择 Markdown · 工作原理 · easy-notion-mcp 提供哪些工具? · 有哪些可用的 MCP 资源? · easy-notion-mcp 支持哪些 block 类型? · 我能否在保留格式的情况下读取和重写页面? · easy-notion-mcp 如何处理数据库? · 适用于你自己的智能体的 Cookbook 配方 · 安全性和提示注入怎么办? · 稳定性和版本控制 · 常见问题 · 社区
easy-notion-mcp 与其他 Notion MCP 服务器相比如何?
功能 | easy-notion-mcp | 官方 Notion MCP (npm) | better-notion-mcp |
内容格式 | ✅ 标准 GFM markdown | ❌ 原始 Notion API JSON | ⚠️ Markdown(block 类型有限) |
Block 类型 | ✅ 24(toggles、columns、callouts、equations、embeds、tables、file uploads、task lists) | ⚠️ 全部(以原始 JSON 形式) | ⚠️ ~7(headings、paragraphs、lists、code、quotes、dividers) |
往返支持 | ✅ 24 种 block 类型,有文档记录的注意事项 | ❌ 原始 JSON 需要重建 block | ⚠️ 不支持的 block 会被静默丢弃 |
工具 | 43 个独立命名的工具 | 18 个从 OpenAPI 自动生成 | 9 个复合工具(39 个操作) |
文件上传 | ✅ markdown 中的 | ❌ 开放的功能请求 | ✅ 5 步生命周期 |
提示注入防御 | ✅ 内容提示前缀 + URL 清理 | ❌ | ❌ |
数据库条目格式 | 简单的 | 简化的键值对 | 简化的键值对 |
认证选项 | API token 或 OAuth | API token 或 OAuth | API token 或 OAuth |
easy-notion-mcp 能节省多少 token?
读取页面内容的响应 token 消耗比官方 Notion MCP 服务器少约 6–7×,因为 Notion 的原始 block JSON 携带了每个 block 的元数据(block ID、时间戳、作者对象),而阅读内容的智能体根本不需要这些。通常在 ~5–7× 之间,从代码密集型页面的 ~3× 到内容丰富的页面的 ~15×,页面内容的 ≥94% 得以保留。与官方原始 JSON 服务器对比测量;与其他基于 markdown 的服务器大致相当。
优势在于省略元数据,而非编码效率。在信息量相同的情况下,两种格式的消耗大致相同(在完整表示的页面形态上,常见的中间表示比率约为 ~1.0–1.06×,在典型散文上为 1.32×),因此节省的是原始 JSON 携带而内容读取从不使用的每 block 元数据(block UUID、时间戳、作者对象、注释包装器)。数据库查询在内容完整度达到 100% 时也显示出类似的 ~7× 优势。
方法论、各类别结果以及所有注意事项:.meta/research/token-bench-results-2026-06-13.md(可通过 scripts/bench/lib/recompute-tiers.ts 重新运行)。
Related MCP server: MCP Notion Server (@suncreation)
如何设置 easy-notion-mcp?
使用 API token
创建一个 Notion 集成,复制 token,并将你的页面共享给它。
Claude Code:
claude mcp add notion -s user \
-e NOTION_TOKEN=ntn_your_integration_token \
-- npx -y easy-notion-mcp这会将服务器注册到你的 Claude Code 用户级配置(-s user)中,并通过 -e 将 NOTION_TOKEN 直接传递给 MCP 子进程。你的 shell 环境和 rcfile 不会被改动 —— token 存放在 Claude Code 的配置文件中,作用域限定于此服务器,其他进程不可见。要为 create_page 设置默认父页面,请在同一个命令中添加 -e NOTION_ROOT_PAGE_ID=<page-id>。
OpenClaw:
openclaw config set mcpServers.notion.command "npx"
openclaw config set mcpServers.notion.args '["-y","easy-notion-mcp"]'然后在启动 OpenClaw 之前,通过父 shell 环境提供 token:
export NOTION_TOKEN=ntn_your_integration_token这种 export 形式是任何继承父 shell 环境的 MCP 客户端的通用后备方案。注意:除非你将其添加到 shell rcfile 中(这本身有安全影响),否则它只对当前 shell 会话有效 —— 特别是在使用 Claude Code 时,请优先使用上面的 -e 形式。
Claude Desktop / Cursor / Windsurf —— 添加到你的 MCP 配置文件中:
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "easy-notion-mcp"],
"env": {
"NOTION_TOKEN": "ntn_your_integration_token"
}
}
}
}配置文件位置:Claude Desktop → claude_desktop_config.json · Cursor → .cursor/mcp.json · Windsurf → ~/.windsurf/mcp.json
{
"servers": {
"notion": {
"command": "npx",
"args": ["-y", "easy-notion-mcp"],
"env": {
"NOTION_TOKEN": "ntn_your_integration_token"
}
}
}
}用于低上下文 Notion 访问的 CLI 配置文件
当智能体需要访问 Notion 但不想加载完整的 MCP 工具面时,或者当你希望为不同的权限模式使用独立的 Notion 集成时,请使用 easy-notion CLI。配置文件默认位于 ~/.config/easy-notion-mcp/profiles.json,引用的是环境变量名,而非原始 token。
export NOTION_WORK_READONLY=ntn_readonly_token
export NOTION_WORK_WRITE=ntn_readwrite_token
npx -y --package easy-notion-mcp easy-notion profile add work-ro \
--token-env NOTION_WORK_READONLY \
--mode readonly \
--default
npx -y --package easy-notion-mcp easy-notion profile add work-rw \
--token-env NOTION_WORK_WRITE \
--mode readwrite \
--root-page-id your_root_page_id读取命令适用于只读配置文件:
npx -y --package easy-notion-mcp easy-notion --profile work-ro search "roadmap" --filter pages
npx -y --package easy-notion-mcp easy-notion --profile work-ro page read PAGE_ID --include-metadata
npx -y --package easy-notion-mcp easy-notion --profile work-ro content search-in-page PAGE_ID --query "launch" --within-toggle "Script"修改命令需要读写配置文件:
npx -y --package easy-notion-mcp easy-notion --profile work-rw content append PAGE_ID --markdown "## Update"
npx -y --package easy-notion-mcp easy-notion --profile work-rw content update-toggle PAGE_ID --title "Script" --markdown-file ./script.md
npx -y --package easy-notion-mcp easy-notion --profile work-rw content archive-toggle PAGE_ID --title "Done"
npx -y --package easy-notion-mcp easy-notion --profile work-rw content restore-toggle ARCHIVED_BLOCK_ID破坏性 CLI 命令支持 --dry-run 作为只读预检。它会在可能的情况下运行相同的查找和 markdown 验证,返回计划中的字段,如 would_delete_block_ids、would_update、would_archive 或 would_restore,并且不会修改 Notion。
用于智能体路由的轻量级技能发布在本仓库的 skills/easy-notion-cli/ 中。它教导智能体优先使用 CLI 进行基于配置文件的 Notion 访问,而不是注册多个 MCP 服务器。
使用 OAuth
API token + stdio 是摩擦更低的默认方案。如果你运行的是共享部署,或者需要按用户访问,OAuth 可以处理认证,无需复制粘贴 token。
启动服务器:
npx -p easy-notion-mcp easy-notion-mcp-http需要 NOTION_OAUTH_CLIENT_ID 和 NOTION_OAUTH_CLIENT_SECRET 环境变量。请参阅下面的 OAuth 设置。
Claude Code:
claude mcp add notion --transport http http://localhost:3333/mcpOpenClaw:
openclaw config set mcpServers.notion.transport "http"
openclaw config set mcpServers.notion.url "http://localhost:3333/mcp"Claude Desktop:
前往设置 → 连接器 → 添加自定义连接器,输入 http://localhost:3333/mcp。
你的浏览器将打开 Notion 的授权页面。选择要共享的页面,点击允许,完成。
如果你想按项目而不是按用户注册 easy-notion-mcp,请将以下内容粘贴到 你的 项目根目录下的 .mcp.json 文件中:
{
"mcpServers": {
"easy-notion-mcp": {
"command": "npx",
"args": ["-y", "easy-notion-mcp"],
"env": {
"NOTION_TOKEN": "ntn_your_integration_token",
"NOTION_ROOT_PAGE_ID": "your_root_page_id"
}
}
}
}将占位符值替换为你的真实 Notion 集成 token 和(可选的)根页面 ID。请注意,此文件应放在 你的 项目中,而不是本仓库中 —— Claude Code 会自动注册它在项目级 .mcp.json 中找到的任何服务器并尝试启动它,因此提交一个包含占位符凭据的文件会在打开仓库时导致“连接失败”。
Dify / n8n / FlowiseAI(基于 Docker 的平台):
在你的宿主机上运行 HTTP 服务器:
export NOTION_MCP_BEARER=$(openssl rand -hex 32)
NOTION_TOKEN=ntn_your_integration_token \
NOTION_MCP_BIND_HOST=0.0.0.0 \
NOTION_MCP_BEARER=$NOTION_MCP_BEARER \
npx -p easy-notion-mcp easy-notion-mcp-http在你平台的 MCP 服务器设置中,使用 host.docker.internal 而不是 localhost,并将 bearer 添加到请求头中:
http://host.docker.internal:3333/mcp
Authorization: Bearer <your NOTION_MCP_BEARER value>为什么不用 localhost? 这些平台通常在 Docker 中运行。容器内的
localhost指的是容器本身,而不是你的宿主机。host.docker.internal弥补了这一差距。HTTP 主机和 bearer: HTTP 服务器默认绑定
127.0.0.1,静态 token 模式需要NOTION_MCP_BEARER。host.docker.internal访问的是主机的桥接 IP,因此请在主机上设置NOTION_MCP_BIND_HOST=0.0.0.0,并在每个客户端请求中发送 bearer 头。对于共享 Docker 部署,OAuth 模式(为每个用户签发 bearer)是另一种选择。
easy-notion-mcp 可与任何兼容 MCP 的客户端配合使用。服务器通过 stdio(API token 模式)或 HTTP(OAuth 或 API token 模式)运行。
如果在设置过程中遇到问题,Discord 社区 是一个提问的好地方。#easy-notion-mcp 频道涵盖设置和设计讨论。Bug 请提交到 GitHub issues。
配置
Stdio 模式(API token)
变量 | 是否必需 | 默认值 | 描述 |
| 是 | — | Notion API 集成 token |
| 否 | — | 默认父页面 ID |
| 否 |
| 在 markdown 读取响应( |
关于
.env文件(仅限贡献者): easy-notion-mcp 通过dotenv从当前工作目录加载.env文件。实际上,这意味着只有当你从克隆的仓库检出目录运行服务器时(在npm install && npm run build之后执行node dist/index.js),.env才会“直接生效”,因为仓库根目录就是你的当前工作目录。当通过npx easy-notion-mcp或从任意目录全局安装来调用该包时,它不会被加载——这是标准的 npm CLI 行为。对于npx方式,请通过上文 Claude Code 设置 中的-e标志传递NOTION_TOKEN,或通过你的 MCP 客户端配置中的env块传递。
OAuth / HTTP 传输
运行 npx -p easy-notion-mcp easy-notion-mcp-http 以启动支持 OAuth 的 HTTP 服务器。
变量 | 是否必需 | 默认值 | 描述 |
| 是(OAuth 模式) | — | Notion 公共集成的 OAuth 客户端 ID |
| 是(OAuth 模式) | — | Notion 公共集成的 OAuth 客户端密钥 |
| 否 |
| HTTP 服务器端口 |
| 否 |
| OAuth 回调 URL |
| 否 |
| 绑定地址。默认为回环地址;设置为 |
| 是(静态令牌模式) | — | 静态令牌 HTTP 模式下客户端所需的共享密钥 bearer 令牌。没有它服务器将拒绝启动。OAuth 模式下不需要。 |
要获取 OAuth 凭据,请在 notion.so/profile/integrations 创建一个公共集成,并将 http://localhost:3333/callback 配置为重定向 URI。
在 OAuth 模式下,create_page 无需 NOTION_ROOT_PAGE_ID 即可工作——页面默认创建在用户的私有工作区部分。
HTTP 模式安全态势
HTTP 传输专为可信网络设计:单操作员自托管使用 bearer 密钥,或共享部署使用 OAuth。它并未针对直接暴露于开放互联网进行加固;如果你需要远程访问,请在其前面放置一个带 TLS 的反向代理。
静态令牌模式需要 bearer 令牌。 仅设置 NOTION_TOKEN 就启动 npx -p easy-notion-mcp easy-notion-mcp-http 将拒绝启动。请在服务器环境中设置一个共享密钥 bearer 令牌,然后配置你的 MCP 客户端,在每个 /mcp 请求中将其作为 Authorization: Bearer <secret> 发送:
export NOTION_MCP_BEARER=$(openssl rand -hex 32)
NOTION_TOKEN=ntn_your_integration_token npx -p easy-notion-mcp easy-notion-mcp-http该 bearer 令牌通过 crypto.timingSafeEqual 进行比较。缺失或错误的 bearer 令牌会收到 401 { "error": "invalid_token" }。通过使用新值重启服务器来轮换密钥。
默认绑定为回环地址。 服务器默认绑定 127.0.0.1——仅限本地进程。设置 NOTION_MCP_BIND_HOST=0.0.0.0 可暴露所有接口,或设置特定 IP(如 192.168.1.5)以暴露单个接口。无论绑定如何,都需要 bearer 令牌。
始终使用 bearer 令牌是信任边界。 /mcp 端点未启用 DNS 重绑定保护,OAuth 注册/令牌端点(/register、/token、/revoke)上的 CORS 是宽松的。请将 bearer 令牌(或 OAuth 的每用户 bearer 令牌)视为网络与你的 Notion 工作区之间唯一的屏障。即使是仅回环部署也要保持设置。如果你需要将此服务器暴露到可信网络之外,请将其放在处理 TLS 和来源检查的反向代理之后。
OAuth 模式适用于多用户/远程。 OAuth 有自己的每用户 bearer 强制机制;OAuth 模式下不需要 NOTION_MCP_BEARER。对于共享部署,OAuth 的每用户身份模型是合适的形式——静态令牌 + bearer 令牌适用于单操作员自托管。
file:// 上传仅限 stdio。 通过 HTTP 向 create_page、append_content、replace_content、update_section 或 update_page.cover 传递包含 file:// URL 的 Markdown 会被拒绝。对于本地文件工作流,请使用 stdio 模式(create_page_from_file 也仅限 stdio),或将文件托管到 HTTPS URL,并在 Markdown 中使用该 URL。

为什么以 Markdown 为先?
官方 Notion MCP npm 包返回原始 API JSON——深度嵌套的块对象,每个块带有约 120 个 token 的元数据。其他服务器会转换为 markdown,但只支持少数块类型,会静默丢弃标注(callout)、折叠块(toggle)、表格、公式等。
easy-notion-mcp 使用智能体已经熟悉的标准 GFM markdown。无需学习新内容,没有自定义标签语法,也不需要构造块对象。智能体编写 markdown,easy-notion-mcp 负责转换为 Notion 的块 API——以及反向转换,并保留 24 种块类型。
这意味着智能体可以编辑现有内容。读取页面,取回 markdown,修改字符串,再写回。对于此服务器所表示的块类型,受支持的格式和结构都会保留,已知的遗漏和降级情况记录如下。智能体编辑 Notion 页面的方式与编辑代码相同——都是作为文本来编辑。
easy-notion-mcp 是如何工作的?
页面 — 写入和读取 markdown:
create_page({
title: "Sprint Review",
markdown: "## Decisions\n\n- Ship v2 by Friday\n- [ ] Update deploy scripts\n\n> [!WARNING]\n> Deploy window is Saturday 2–4am only"
})读回时——得到相同的 markdown:
read_page({ page_id: "..." }){ "markdown": "## Decisions\n\n- Ship v2 by Friday\n- [ ] Update deploy scripts\n\n> [!WARNING]\n> Deploy window is Saturday 2–4am only" }修改字符串,调用 replace_content,完成。或者通过 update_section 按标题名称定位单个部分。或者执行精准的 find_replace,而不影响页面的其余部分。页面还可以通过 create_page 或 update_page 设置表情符号图标和封面图片。
数据库 — 写入简单的键值对:
add_database_entry({
database_id: "...",
properties: { "Status": "Done", "Priority": "High", "Due": "2026-05-15", "Tags": ["v2", "launch"] }
})不需要属性类型对象,也不需要嵌套的 { select: { name: "Done" } } 包装。easy-notion-mcp 在运行时获取数据库模式并自动转换。智能体传入 { "Status": "Done" },easy-notion-mcp 完成其余工作。
错误会告诉你如何修复。 错误的标题名称会返回可用的标题。页面缺失会提示你将其分享给集成。无效的过滤器会告诉你先调用 get_database。智能体无需向用户求助即可自行纠正。
复杂内容也能处理。 折叠块中嵌套折叠块、混合内容类型的列(列表 + 代码块 + 引用块)、深层列表嵌套,以及完整的 Unicode(日文、中文、阿拉伯文、表情符号)都包含在往返测试中。update_section 的标题搜索不区分大小写,未命中时返回可用标题。add_database_entries 处理部分失败,成功和失败的条目会分别返回,因此智能体可以只重试失败的条目。

easy-notion-mcp 提供哪些工具?
easy-notion-mcp 包含 7 个类别中的 43 个独立命名的工具(HTTP 上为 42 个,其中不包括仅限 stdio 的 create_page_from_file)。工具描述将安全关键行为内联呈现,并指向 MCP 资源以获取更长的参考资料,例如 markdown 语法、警告结构、属性分页和 update_data_source 示例。
页面(20 个工具)
工具 | 描述 |
| 从 markdown 创建页面 |
| 从本地 markdown 文件创建页面(仅限 stdio) |
| 将页面作为 markdown 读取 |
| 按标题名称读取一个部分 |
| 按 ID 读取一个块,包括容器的嵌套子块 |
| 按标题读取一个折叠块或可折叠标题 |
| 在页面或一个折叠块中搜索原始块文本 |
| 向页面追加 markdown |
| 原子地替换所有页面内容(保留匹配块的块 ID) |
| 按标题名称更新一个部分;可选择保留标题的正文替换(破坏性;对于不可替代的内容,请先使用 duplicate_page) |
| 按标题更新一个折叠块的正文(破坏性;保留折叠块容器 ID) |
| 按标题归档一个折叠块或可折叠标题 |
| 按已归档的块 ID 恢复已归档的折叠块或可折叠标题 |
| 查找并替换文本,保留文件 |
| 按 ID 更新单个块(保留块的标识,以支持深层链接和评论) |
| 更新标题、图标或封面 |
| 复制页面及其内容 |
| 将页面移至回收站 |
| 将页面移动到新的父级 |
| 恢复已归档的页面 |
破坏性工具支持 dry_run: true 作为预检。dry-run 不会上传或校验本地 file:// Markdown 上传,因为那会创建 Notion 上传;对于本地文件,请使用 HTTPS URL,或在非 dry-run 模式下运行。replace_content 的 dry-run 会翻译 Markdown 并返回翻译器警告,但它无法呈现 Notion 侧的 unmatched_blocks 或 truncated 字段,因为它不会调用 Notion 的更新端点。
restore_toggle 有意基于 ID:传入 archive_toggle 返回的已归档块 ID。Notion 不提供已归档子块的枚举来支持标题搜索,也没有 read_page include_archived 工作流,因此无法按标题恢复。
导航(3 个工具)
工具 | 描述 |
| 列出父页面下的子页面,每行包含 |
| 搜索页面和数据库 |
| 获取可分享的 URL |
每一行 list_pages 返回 id、title、created_time 和 last_edited_time,因此代理无需逐页往返即可区分活跃页面和过期页面。时间戳直接来自 Notion,精确到分钟,last_edited_time 会在页面内容和属性编辑时更新。请注意它与 search 的刻意区别:search 只返回日期形式的 last_edited,而 list_pages 返回完整的 ISO-8601 时间戳 last_edited_time。
数据库(9 个工具)
工具 | 描述 |
| 创建具有类型化架构的数据库 |
| 更新数据库架构(添加、重命名或删除属性;更改标题;移至回收站或恢复) |
| 获取数据库架构、属性名称和选项 |
| 列出集成可以访问的所有数据库 |
| 使用筛选器、排序或文本搜索进行查询 |
| 使用简单的键值对添加一行 |
| 在一次调用中添加多行 |
| 使用简单的键值对更新一行 |
| 删除(归档)一个数据库条目 |
数据库写入工具会拒绝未知属性名称和不支持的属性类型,并给出明确错误,而不是静默丢弃。 请先调用
get_database确认属性名称和类型。写入支持的属性类型:title、rich_text、number、select、multi_select、date、checkbox、url、phone、status、relation、people。对于people,传入单个用户 ID 字符串或用户 ID 数组。计算类型(formula、rollup、unique_id、created_time、last_edited_time、created_by、last_edited_by)由 Notion 填充,无法通过 API 设置。files、verification、place、location和button的值写入也会被拒绝。对于关系写入,传入单个页面 ID 字符串("Projects": "page-id")或数组("Projects": ["id-a", "id-b"]);空数组会清除该关系。
easy-notion-mcp 会获取数据库架构,将值映射为 Notion 的属性格式,并在代理传入类似 { "Status": "Done" } 的简单键值对时自动处理类型转换。架构会缓存 5 分钟,以避免批量操作期间产生冗余 API 调用。
视图(6 个工具)
工具 | 描述 |
| 列出数据库或数据源的已保存视图 |
| 获取某个已保存视图的原始配置 |
| 通过已保存视图查询条目 |
| 创建表格、列表、看板、日历、画廊或时间线视图 |
| 重命名或更新已保存视图的原始筛选/排序/配置字段 |
| 在明确确认后删除已保存视图 |
评论(2 个工具)
工具 | 描述 |
| 列出页面上的评论 |
| 向页面添加评论 |
用户(2 个工具)
工具 | 描述 |
| 列出工作区用户 |
| 获取当前机器人用户 |
服务器(1 个工具)
工具 | 描述 |
| 报告服务器自身的设置:版本、传输方式、工作区根目录和可见工具数量 |
当文件路径或配置错误让你无从下手时,get_config 就是你要用的工具。create_page_from_file 只接受工作区根目录内的路径;当路径超出该范围时,拒绝信息现在会指明解析后的根目录。get_config 让你直接读取该根目录,而无需推断。在 HTTP 模式下,工作区根目录不适用,因此路径字段为 null,状态为 not_applicable;服务器绝不会向 HTTP 调用方报告主机路径。
有哪些 MCP 资源可用?
支持 MCP 资源的客户端可以按需读取这些文档,而无需将所有参考材料加载到每个工具描述中:
资源 URI | 内容 |
| 页面写入和读取所支持的 Markdown 语法 |
| 警告代码和响应形状 |
|
|
|
|
easy-notion-mcp 支持哪些块类型?
easy-notion-mcp 支持 24 种 Notion 块类型,使用标准 Markdown 语法,并扩展了针对 Notion 特有块(如开关、分栏和标注)的约定。代理编写熟悉的 Markdown——easy-notion-mcp 负责与 Notion 块格式之间的相互转换。
标准 Markdown
语法 | Markdown |
标题 |
|
粗体、斜体、删除线 |
|
行内代码 |
|
链接 |
|
图片 |
|
无序列表 |
|
有序列表 |
|
任务列表 |
|
引用块 |
|
代码块 |
|
表格 | 标准管道表格语法 |
分隔线 |
|
Notion 特有语法
块 | 语法 |
开关 |
|
分栏 |
|
标注(备注) |
|
标注(提示) |
|
标注(警告) |
|
标注(重要) |
|
标注(信息) |
|
标注(成功) |
|
标注(错误) |
|
公式 |
|
目录 |
|
嵌入 |
|
书签 | 单独成行的裸 URL |
文件上传(图片) |
|
文件上传(文件) |
|
换行与 collapse_soft_wraps
默认情况下,段落内的单个换行符会原样写入。因此,在固定列处硬换行的 Markdown(大多数仓库中的惯例)到达 Notion 时会带有这些换行。该默认行为没有改变。
每个写入 Markdown 的工具都接受可选的 collapse_soft_wraps: true,它会改为应用 CommonMark 的软换行语义:段落内的单个换行符变为空格,因此硬换行的文件会以流畅的段落形式到达。空行仍然分隔块,围栏代码块在两种模式下都不受影响。
easy-notion page create-from-file --title "Design notes" --file ./NOTES.md --collapse-soft-wraps在重新上传从 Notion 读回的内容时,不要使用该选项,否则有意的换行会丢失。
显式硬换行(末尾反斜杠或两个末尾空格)无论是否设置该选项,行为都相同,但会因写入路径而异:
写入路径 | 硬换行行为 |
| 保留在块内 |
| Notion 的增强 Markdown 导入会将段落内的换行渲染为单独的段落,因此硬换行会以段落拆分的形式到达 |
这种差异是导入路径的属性,而不是 collapse_soft_wraps 的属性。
标题与开头 H1 重复
create_page 和 create_page_from_file 接受可选的 strip_leading_h1: true,它会移除文档开头的 H1,这样以你传入的 title 作为开头标题的文件不会在页面上重复出现该标题。它仅当第一个转换后的顶级块是普通(不可切换)的 heading_1 时生效,默认值为 false。
easy-notion page create-from-file --title "Design notes" --file ./NOTES.md --strip-leading-h1create_page、create_page_from_file、append_content、replace_content、update_section 和 update_toggle 接受 return_block_map: false,以便在不需要时省略 block_map;默认值仍为 true 且保持不变。
我能否在保留格式的情况下读取和重写页面?
可以,对于此服务器所代表的 markdown 约定而言。往返支持覆盖 24 种块类型。已知的遗漏和降级情况均有文档记录,其中许多会通过显式警告报告。
read_page 返回 create_page 接受的 markdown 约定:标题、列表、表格、标注、折叠块、分栏、公式和页面提及。
当页面包含此服务器尚不支持的 Notion 块类型(如 synced_block、child_database、child_page 或 link_to_page)时,read_page 会包含一个 warnings 字段,其中代码为 omitted_block_types,列出被省略的块 ID 和类型。通过 replace_content 将该 markdown 写回会删除这些块,因此该警告可让代理避免不安全的改写。对于内联页面提及,请使用 @[Title](notion-url),这是与 link_to_page 块类型不同的独立结构。
Notion AI 会议记录(以及已弃用的 transcription)块会渲染为一个合成折叠块,其中包含标题、可选的录制时间戳,以及 ## Summary / ## Notes 部分;只有使用 read_page include_transcript: true 时才会包含转录文本。这些渲染读取会发出 read_only_block_rendered 警告,以提示将该 markdown 写回会用普通块替换原生会议块。
某些降级不会以警告形式报告。在 replace_content 路径上,书签和嵌入会以裸 URL 形式写入(这些确实会产生警告),而 file、audio 和 video 块会被静默缩减为它们的 URL。下划线和彩色文本注释无法用 markdown 表示,在读取和写入时会被静默丢弃。
easy-notion-mcp 使代理能够读取页面、修改 markdown 字符串并写回,同时保留受支持的格式、结构和内容。无需格式转换。无需块重建。代理编辑 Notion 页面的方式与编辑代码相同——以文本形式。
find_replace 和 replace_content 之间有什么区别?
easy-notion-mcp 为不同用例提供了三种编辑策略:
replace_content— 用新的 markdown 替换页面上的所有内容。最适合整体重写。update_section— 替换由标题名称标识的单个部分。默认情况下,替换 markdown 包含标题并替换整个部分。传入preserve_heading: true(或 CLI--preserve-heading)可保留现有标题的块 ID、文本、类型、评论和可折叠状态,同时仅破坏性地替换该部分的主体。find_replace— 在页面任意位置查找并替换特定文本,保留所有其他内容和附件。最适合精准编辑。
在破坏性编辑之前,如果你想要预检响应而不是实际变更,请在 MCP 工具上传入 dry_run: true,或在 CLI 中传入 --dry-run。
easy-notion-mcp 如何处理数据库?
easy-notion-mcp 提供 9 个数据库工具,抽象掉了 Notion 复杂的属性格式。代理传入简单的键值对,如 { "Status": "Done", "Priority": "High" };easy-notion-mcp 在运行时获取数据库架构,缓存 5 分钟,并自动转换为 Notion 的属性格式。
easy-notion-mcp 支持使用类型化架构创建和更新数据库、使用过滤器和排序进行查询,以及通过 add_database_entries 进行批量操作(一次调用多行)。
食谱:为你自己的代理准备的配方
这些配方将你自己的代理指向 Notion。代理拥有智能;easy-notion-mcp 通过现有的 MCP 工具提供确定性的连接纽带,因此这些配方可按需运行,无需二次安装。它们是免费且自主的:你自己的代理、你自己的令牌、无需 OAuth 的 API 令牌设置,以及免费套餐的数据库查询。
当等效工具启用时,这些步骤可通过 MCP 工具或 claude.ai 连接器完成。配方 2 还可通过 skills/easy-notion-cli/ 中的 easy-notion CLI 技能完成;配方 1 需要 create_database、使用 search_in_page 进行源块查找,以及结构化的去重过滤器,而当前的 CLI 界面并未暴露这一完整工作流。Claude Code 代理可以使用 skills/notion-recipes/ 中的操作技能。
配方 1:从会议记录到行动项
此配方将会议记录页面或粘贴的笔记转换为 Action Items 数据库中的去重行。工具序列为:先执行一次 create_database,然后每次运行时,当源是页面时执行 read_page,使用 search_in_page 解析每个项目的源块 ID,对每个候选项目使用带有精确 Item Key 过滤器的 query_database,使用 add_database_entry 或 add_database_entries 添加新行,最后执行 query_database 进行验证。
经过验证的实际结果是,一次规划会议产生了 5 行。缺失的负责人和截止日期存储在 Flags 多选字段中,而不是 Source 中;一个 query_database 过滤器 {"property":"Item Key","rich_text":{"equals":"38bbe876-242f-81f1-97b7-df935d050a24:38bbe876-242f-81c9-86c6-d9a792fc70b7"}} 恰好返回 1 行。对相同笔记运行两次后,计数仍为 5,且零重复。对共享会议名称进行自由文本搜索会返回每一行,因为它也扫描了 Source,因此此配方使用精确的 Item Key 过滤器进行去重。
安全边界:配方 1 可安全重跑且具有幂等性,因为 Item Key 存储的是源行的稳定 Notion 身份(<pageId>:<blockId>),而不是行动措辞。
面向 claude.ai 连接器用户的复制粘贴内容,配方 1
Use the enabled easy-notion or Notion connector tools to turn my meeting notes into an Action Items database.
Note: the simple {"Property":"Value"} write format below assumes the easy-notion tools. If only the official Notion connector is enabled, wrap each value in its Notion property-type object instead.
Inputs I will provide:
- Meeting notes page or pasted meeting notes: <MEETING_NOTES_PAGE_OR_TEXT>
- Parent page for the database, if a new database is needed: <PARENT_PAGE>
- Existing Action Items database, if one already exists: <DATABASE_NAME_OR_ID>
If an Action Items database does not already exist, create one with these properties:
- Name: title
- Item Key: rich_text
- Owner: rich_text
- Due: date
- Status: status
- Flags: multi_select
- Source: rich_text
Read the meeting notes or use the pasted notes. Extract only discrete action items. For each item, derive:
- Name: the action text
- Owner: the named assignee, or blank
- Due: the stated date as ISO YYYY-MM-DD, or blank
- Item Key: the source line's stable identity, formatted as <sourcePageId>:<sourceBlockId>
- Source: the meeting title plus date, with no flags stashed here
- Status: Not started
- Flags: add needs-owner if no owner, and needs-due if no due date
Resolve sourceBlockId with search_in_page. read_page returns markdown without block IDs. For a Notion-page source, call read_page to extract items, then for each item call search_in_page with a verbatim, distinctive substring of that item's original source line. Use the matches[].block_id whose text is that source line. If several blocks match, use a longer verbatim substring to isolate one block. For pasted notes, first save them as a Notion page with create_page, then proceed through search_in_page. Do not rely on block IDs from create_page, which returns only {id,title,url}. If one source line contains multiple distinct actions, append a stable ordinal suffix in source order, such as :1 or :2, to keep keys unique.
Before inserting each item, dedupe with an exact Item Key filter:
{"property":"Item Key","rich_text":{"equals":"<that item's key>"}}
If the query returns no results, insert the row with simple key-value properties. If it returns a result, skip that item. Do not dedupe with free-text database search, because text search also scans Source and can false-match every row from the same meeting.
After inserting, query the database and summarize the rows created and skipped.
Re-running is safe and idempotent because the exact Item Key filter uses the source line's stable Notion identity, not the action wording.配方 2:批量编辑、查找替换与修复
此配方涵盖两个代理可以超越 Notion 原生限制进行迭代的方面:数据库属性修复和页面正文查找替换。对于数据库修复,序列为:get_database、遍历所有行的 query_database、构建规范化映射、对需要修复的行执行 update_database_entry,然后重新查询。对于页面文本,序列为:使用 dry_run: true 的 find_replace、使用 replace_all: true 的 find_replace,然后执行 read_page 进行验证。
经过验证的实际数据库修复将 4 行中混合的 Eng 和 engineering 值规范化为一个一致的选项,同时保持无关行不变。经过验证的实际页面编辑替换了段落和标题正文中的 4 处内容。注意:select 和 status 选项匹配不区分大小写,写入时会吸附到最早存在的选项的大小写形式。如果已存在小写变体,写入大写版本会复用现有小写选项。若要强制特定大小写,请在 Notion 的 UI 中重命名该选项,而不是写入新的大小写形式。
面向 claude.ai 连接器用户的复制粘贴内容,配方 2
Use the enabled easy-notion or Notion connector tools to repair Notion database rows or replace repeated text in a Notion page.
Note: the simple {"Property":"Value"} write format below assumes the easy-notion tools. If only the official Notion connector is enabled, wrap each value in its Notion property-type object instead.
Inputs I will provide:
- Target database for property repair: <DATABASE_NAME_OR_ID>
- Property to normalize: <PROPERTY_NAME>
- Normalization map, for example {"Eng":"Engineering","engineering":"Engineering"}
- Target page for find-replace, if needed: <PAGE_NAME_OR_ID>
- Find text and replacement text, if needed: <FIND_TEXT> -> <REPLACE_TEXT>
For database property repair:
1. Get the database schema so you know the exact property names. If select or status options are missing from the schema, query live rows and read the current values from the results.
2. Query the database rows. If the database is large, page through all results in a loop.
3. Build or use the normalization map I provide.
4. For each row whose property value needs fixing, update that row with a simple key-value map such as {"<PROPERTY_NAME>":"<CANONICAL_VALUE>"}.
5. Re-query the database and summarize how many rows changed and which values remain.
Important caveat: select and status option matching is case-insensitive, and writes snap to the earliest-existing option's casing. If a lowercase variant already exists, writing a capitalized version may reuse the lowercase option. To force specific casing, I need to rename the option in Notion's UI.
For page-body find-replace:
1. Run a dry-run find-replace with replace_all enabled and report the match count before changing anything.
2. If the match count is expected, run find-replace with replace_all enabled.
3. Read the page afterward and verify the replacement.安全性和提示注入呢?
easy-notion-mcp 为生产部署包含两层安全机制:
提示注入加固: Markdown 读取响应(read_page、read_section、read_block 和 read_toggle)包含一个内容提示前缀,指示代理将 Notion 数据视为内容而非指令。search_in_page 返回的原始片段/文本也应同样对待。这降低了页面内容引导代理行为的风险;最终行为取决于模型和客户端。如果你控制工作区,可设置 NOTION_TRUST_CONTENT=true 来禁用 markdown 提示。
URL 清理: javascript:、data: 和其他不安全的 URL 协议会被剥离并渲染为纯文本。仅允许 http:、https: 和 mailto:。

稳定性与版本管理
easy-notion-mcp 遵循 语义化版本控制。自 1.0.0 起,公共契约被冻结为仅做增量变更:工具名称、工具输入模式、工具返回形状、自定义 markdown 约定以及警告代码词汇表,在未来的 2.0 版本发布之前不会以破坏性方式更改。增量变更(新工具、新可选参数、新可选响应字段、新警告代码)不属于破坏性变更,可以在次要版本中发布。
两个层面不在冻结范围内:OAuth / HTTP 身份验证契约是实验性的,在其安全态势成熟之前可能会发生变化;easy-notion CLI 处于 1.0 之前版本,尚未覆盖。完整的契约声明和每个版本的历史记录请参阅 CHANGELOG。
常见问题
easy-notion-mcp 与官方 Notion MCP 服务器有何不同?
官方 Notion MCP npm 包(@notionhq/notion-mcp-server)是一个原始 API 代理,返回未修改的 Notion JSON,因此读取一个页面的响应令牌消耗大约是 easy-notion-mcp 的 markdown 的 6–7 倍。easy-notion-mcp 将所有内容转换为代理已经熟悉的标准 GFM markdown,支持 24 种块类型并带有文档记录的往返注意事项,并且包含提示注入加固。Notion 还提供了一个单独的托管远程 MCP 服务器(基于 OAuth),使用自定义的基于 HTML 标签的 markdown 格式,而 easy-notion-mcp 使用标准 markdown 语法。
easy-notion-mcp 支持哪些 MCP 客户端?
easy-notion-mcp 可与任何兼容 MCP 的客户端配合使用,包括 Claude Desktop、Claude Code、Cursor、VS Code Copilot、Windsurf 和 OpenClaw。它同时支持 stdio 传输(API 令牌)和 HTTP 传输(OAuth)。有关每个客户端的可复制粘贴配置,请参阅 设置说明。
easy-notion-mcp 支持文件上传吗?
支持。easy-notion-mcp 支持使用 markdown 语法中的 file:/// 协议进行文件上传。使用  上传图片,使用 [name](file:///path/to/file.pdf) 上传文件。
easy-notion-mcp 能处理嵌套和复杂内容吗?
能。折叠块内嵌套折叠块、包含混合内容类型的分栏(不同分栏中的列表、引用块和代码块)、嵌套的项目符号列表和编号列表,以及完整的 unicode 支持(包括日文、中文、俄文、阿拉伯文和表情符号),这些受支持的结构都有往返测试覆盖。
easy-notion-mcp 能处理批量操作中的部分失败吗?
能。add_database_entries 返回独立的 succeeded 和 failed 数组。如果某个条目验证失败,其他条目仍会被创建。代理可以只重试失败的条目,而无需重新发送整个批次。
社区
社区 Discord 位于 discord.gg/S8cghJSVBU。#easy-notion-mcp 频道涵盖设置问题和设计讨论,服务器的其余部分开放用于展示分享或一般交流。对于错误和具体的功能请求,GitHub issues 仍然是权威渠道。
贡献
欢迎在 GitHub 上提交 Issue 和 PR。
许可证
MIT
Available Tools
43 toolsadd_commentA
Add a comment to a page. Supports inline markdown and page mentions with @Title. Unlike append_content, a mention the integration cannot resolve is not downgraded to a plain link and returns no warning, so the call can fail. Returns { id, content }.
Inputs: text (required), page_id (required), collapse_soft_wraps.
add_database_entriesA
Create multiple entries in a database in one call. Each entry uses the same simple key-value format as add_database_entry. Returns per-entry results — partial failures don't block the batch.
Inputs: entries (required), page_id, database_id.
add_database_entryA
Create one database entry using simple key-value property inputs. Call get_database first to see available property names and valid select/status options.
Writable property values use simple inputs:
title, rich_text: string
number: number
select, status: option name string
multi_select: array of option name strings
date: ISO date string (start only)
checkbox: boolean
url, email, phone: string
relation: string or array of page IDs
people: string or array of user IDs
Not writable from this tool:
formula, rollup, unique_id, created_time, last_edited_time, created_by, last_edited_by: computed by Notion
files, verification, place, location, button: not supported for value writes here
Example: { "Name": "Buy groceries", "Status": "Todo", "Priority": "High", "Due": "2025-03-20", "Tags": ["Personal"] }.
Inputs: properties (required), page_id, database_id.
append_contentA
Append markdown content to an existing page. The server converts markdown into native Notion blocks, not flat/plain text. The server automatically handles Notion API limits: batches more than 100 child blocks, splits rich text over 2000 characters, and writes deeply nested blocks in additional passes, so callers can append large documents in one call with no need to pre-chunk or pre-split. Supports the same syntax as create_page; read resource easy-notion://docs/markdown for the full syntax guide. Page mentions: @Title; a mention the integration cannot resolve is downgraded to a plain link and reported with a mention_target_unresolved warning. Returns: { success: true, blocks_added: }, plus block_map for top-level appended blocks when present and warnings when present.
Inputs: page_id (required), markdown (required), return_block_map, collapse_soft_wraps.
archive_pageC
Archive a page in Notion.
Inputs: page_id (required), dry_run.
archive_toggleA
Archive one toggle by title from a page. Searches recursively and matches plain toggle blocks plus toggleable heading_1, heading_2, and heading_3 blocks using case-insensitive trimmed text. Archives the matched container block; children are not deleted individually. Missing titles return the available toggle titles.
Inputs: title (required), page_id (required), dry_run.
create_databaseA
Create a database under a parent page.
Supported property types and extras:
title
rich_text (alias: text)
number (optional: format, for example "dollar", "percent", "number_with_commas")
select, multi_select, status (optional: options array of strings or {name, color, description})
date, checkbox, url, email, phone
formula (required: expression, for example "prop("Count") * 2")
rollup (required: function, relation_property, rollup_property)
relation (required: data_source_id; optional: relation_type "single_property" or "dual_property", synced_property_name)
unique_id (optional: prefix, for example "ENG")
people, files
created_time, last_edited_time, created_by, last_edited_by
verification, place, location, button
Unknown property types fail with an explicit error. No silent drops.
Inputs: title (required), schema (required), parent_page_id (required), is_inline.
create_pageA
Create a Notion page from markdown as native Notion blocks. Server handles 100-block batching, 2000-char splitting, and deep nesting, so no pre-chunking. Supports stdio-only file:// uploads. Syntax: easy-notion://docs/markdown. Mentions: @Title. Returns { id, title, url, success: true }, note for workspace-parent pages, plus block_map for top-level created blocks when present.
Inputs: title (required), markdown (required), icon, cover, +4 more.
create_page_from_fileA
Create a Notion page from a local markdown file. The server reads and validates the file, then creates the same result as create_page without sending file contents through the agent context. The server converts the markdown to native Notion blocks (not flat text) and automatically handles Notion's limits (100-block batching, 2000-char splitting, deep nesting), so large files need no pre-chunking.
STDIO MODE ONLY. This tool is not available when the server runs over HTTP, because in HTTP mode the server's filesystem belongs to the server host, not the caller.
Restrictions:
file_path must be an ABSOLUTE path (no relative paths, no ~ expansion)
File must be inside the configured workspace root (defaults to the server's process.cwd(); override via the NOTION_MCP_WORKSPACE_ROOT env var)
File extension must be .md or .markdown
File size must be ≤ 1 MB (1,048,576 bytes)
File must be valid UTF-8
Symlinks are resolved and the resolved path must still be inside the workspace root
For supported markdown syntax, read resource easy-notion://docs/markdown. Page mentions: @Title. Returns: { id, title, url, success: true }, plus note only when created as a private workspace page, plus block_map for top-level created blocks when present.
Inputs: title (required), file_path (required), parent_page_id, return_block_map, +2 more.
create_viewA
Create a Notion database view. Pass database_id. Dashboard views and dashboard widget placement are not supported.
Inputs: name (required), type (required), database_id (required), sorts, +4 more.
delete_database_entryB
Delete (archive) a database entry.
Inputs: page_id (required), dry_run.
delete_viewA
Delete a Notion database view. Destructive: confirm must be exactly true.
Inputs: view_id (required), confirm, dry_run.
duplicate_pageA
Duplicate a page. Reads all blocks from the source and creates a new page with the same content that this server can represent. If the source contains block types this server does not yet support (e.g. child_page subpages, synced_block, child_database, link_to_page), those are omitted from the duplicate AND listed in a warnings field with code omitted_block_types. Notion AI meeting notes are duplicated as ordinary toggle/heading/paragraph blocks (summary and notes only — transcripts are not duplicated); a read_only_block_rendered warning is emitted to identify meeting-notes blocks whose native identity was not preserved across the duplicate. Deep-duplication of subpages is not yet supported.
Inputs: page_id (required), title, parent_page_id.
find_replaceA
Find and replace text on a page. Preserves uploaded files and blocks that aren't touched. More efficient than replace_content for targeted text changes like fixing typos, updating URLs, or renaming terms.
Inputs: find (required), page_id (required), replace (required), dry_run, +1 more.
get_configA
Report this server's own settings: version, transport, the workspace root that bounds create_page_from_file file paths, and how many tools are visible. Call this when a file-path or configuration error occurs and you need the server's actual settings rather than a guess. Read-only, makes no Notion API call, and never returns credentials. Returns { version, transport, workspace_root_configured, workspace_root_resolved, workspace_root_status, workspace_root_source, markdown_docs, visible_tools_count }.
Inputs: no named parameters.
get_databaseA
Get a database's schema — property names, types, and select/status options. Call this before query_database or add_database_entry to know the exact property names and valid values.
Inputs: page_id, database_id.
get_meA
Get the current bot user.
Inputs: no named parameters.
get_viewA
Retrieve one Notion database view by ID. Returns a curated summary (id, name, type, url, data_source_id); set include_config: true for the full raw Notion view object.
Inputs: view_id (required), include_config.
list_commentsB
List comments on a page.
Inputs: page_id (required).
list_databasesA
List all databases the integration can access. Returns database names and IDs — use get_database on any result to see its schema.
Inputs: no named parameters.
list_pagesA
List child pages under a parent page. Each row returns id, title, created_time, and last_edited_time. Timestamps are full ISO-8601 values from Notion, rounded to the minute, and last_edited_time advances on page content and property edits.
Inputs: parent_page_id (required).
list_usersB
List workspace users.
Inputs: no named parameters.
list_viewsA
List Notion database views. Pass exactly one of database_id or data_source_id. Returns a curated summary of each view (id, name, type, url, data_source_id) plus pagination cursors; set include_config: true for the full raw Notion view objects.
Inputs: page_size, database_id, start_cursor, data_source_id, +1 more.
move_pageB
Move a page to a new parent page.
Inputs: page_id (required), new_parent_id (required).
query_databaseA
Query a database with optional filters, sorts, or text search. Use text for simple keyword search across title, rich_text, url, email, and phone fields. For advanced filters, pass Notion filter syntax and call get_database first to see property names and valid options.
Response shape: { results: Array, warnings?: Array }. Multi-value properties are capped by max_property_items and can emit truncated_properties; read resources easy-notion://docs/property-pagination and easy-notion://docs/warnings for details.
Inputs: text, sorts, filter, page_id, +2 more.
query_viewB
Query a Notion database view. Creates a temporary view query, fetches database row results, then deletes the query.
Inputs: view_id (required), page_size, start_cursor.
read_blockA
Read one block by ID as markdown. Container blocks are fetched recursively with children. Unsupported root block types return a clear error; unsupported nested blocks are omitted and listed in warnings. Notion AI meeting-notes blocks encountered in the result are rendered as a synthetic toggle and produce a read_only_block_rendered warning. Transcripts are not included from these tools.
Inputs: block_id (required).
read_pageA
Read a page and return metadata plus markdown. Recursively fetches nested blocks and uses the same markdown conventions accepted by create_page. If unsupported block types are omitted from the markdown, they are listed in warnings. Do NOT round-trip markdown through replace_content when omitted_block_types warnings are present; omitted blocks would be deleted.
Notion AI meeting notes are rendered as a synthetic toggle containing the title, an optional recording timestamp callout, and ## Summary / ## Notes heading sections. Transcript sections are included only with include_transcript: true. A read_only_block_rendered warning is emitted whenever such a block is rendered, indicating that round-tripping the markdown through replace_content will replace the native meeting-notes block with ordinary blocks.
Note on max_blocks: the cap counts top-level page blocks only; section descendants of meeting-notes blocks are fetched in full regardless of the cap, consistent with how nested children of normal blocks are fetched.
Long titles are paginated with max_property_items. For markdown conventions, warning shapes, and pagination details, read resources easy-notion://docs/markdown, easy-notion://docs/warnings, and easy-notion://docs/property-pagination.
Inputs: page_id (required), max_blocks, include_metadata, include_transcript, +1 more.
read_sectionA
Read a single page section by heading name. Uses the same heading matching and boundary rules as update_section: headings are matched case-insensitively, H1 sections end at the next heading of any level, and H2/H3 sections end at the next heading of the same or higher level. Includes the heading block itself and recursively renders nested children only for blocks inside the selected section. If unsupported nested block types are omitted, the response includes warnings. Notion AI meeting-notes blocks encountered in the result are rendered as a synthetic toggle and produce a read_only_block_rendered warning. Transcripts are not included from these tools.
Inputs: heading (required), page_id (required).
read_toggleA
Read one toggle by title from a page. Searches recursively and matches plain toggle blocks plus toggleable heading_1, heading_2, and heading_3 blocks using case-insensitive trimmed text. Missing titles return the available toggle titles. Notion AI meeting-notes blocks encountered in the result are rendered as a synthetic toggle and produce a read_only_block_rendered warning. Transcripts are not included from these tools.
Inputs: title (required), page_id (required).
replace_contentA
Replaces all page content with the provided markdown atomically (one Notion API call). Notion's atomic markdown endpoint converts the markdown to native Notion blocks in that one API call. On matched blocks Notion preserves the original block IDs, so deep-link anchors (#block-id) and inline-comment threads attached to those blocks survive the edit. Unmatched blocks (returned in warnings with code unmatched_blocks) are replaced with new IDs.
NOT preserved across replace_content: child_page subpages, synced_block instances, child_database views, and link_to_page references on the source page. Enhanced Markdown has no input form for these, so they are dropped from the new page content. If the source contains them, use duplicate_page first or edit those types via the Notion UI. For an inline page mention, use @Title; that is a separate construct from the link_to_page block type.
Bookmarks and embeds are written as bare URLs (Notion auto-links) and surface a bookmark_lost_on_atomic_replace or embed_lost_on_atomic_replace warning so callers know the rich preview is lost. For supported markdown syntax and warning details, read resources easy-notion://docs/markdown and easy-notion://docs/warnings. Returns: { success: true }, optionally truncated: true, optionally warnings with entries such as { code: "unmatched_blocks", block_ids: [...] }, plus block_map for the resulting top-level blocks when present. A dry run returns { success: true, dry_run: true, operation, page_id, would_update: true } and optionally warnings.
Inputs: page_id (required), markdown (required), dry_run, return_block_map, +1 more.
restore_pageA
Restore an archived page.
Inputs: page_id (required).
restore_toggleA
Restore an archived toggle or toggleable heading by archived block ID. Use the block ID returned by archive_toggle; Notion does not expose archived child enumeration for title search or read_page include_archived.
Inputs: block_id (required), dry_run.
searchA
Search Notion pages or databases. Use filter: 'databases' to find databases by name, then get_database for schema details.
Inputs: query (required), filter.
search_in_pageA
Search raw Notion block plain text inside a page, optionally scoped to one toggle or toggleable heading by title. Matching is case-insensitive plain substring search.
Inputs: query (required), page_id (required), within_toggle.
update_blockA
Update a single block in place by ID. Preserves the block's identity (deep-link anchors and inline-comment threads attached to the block survive the edit). Use this for surgical edits: fixing a heading, toggling a checkbox, rewriting one paragraph. For multi-block edits, use append_content, replace_content, or update_section.
Type lock-in: the markdown must parse to the same block type as the existing block. update_block cannot change a block's type, because Notion's API forbids it. To change a block's type, use replace_content or delete + append.
Updatable types: paragraph, heading_1, heading_2, heading_3, toggle, bulleted_list_item, numbered_list_item, quote, callout, to_do, code, equation. Container blocks (toggle, callout) update first-level content only, and children stay untouched. Non-updatable types (divider, table, image, bookmark, etc.) accept only archived: true to delete the block. Page mentions: @Title.
To delete a block, pass archived: true instead of markdown. Exactly one of markdown or archived is required.
Inputs: block_id (required), checked, dry_run, archived, +2 more.
update_database_entryA
Update an existing database entry using simple key-value property inputs. Pass only properties to change; omitted properties are left unchanged. Call get_database first to see available property names and valid select/status options.
Writable property values use the same simple inputs as add_database_entry:
title, rich_text: string
number: number
select, status: option name string
multi_select: array of option name strings
date: ISO date string (start only)
checkbox: boolean
url, email, phone: string
relation: string or array of page IDs
people: string or array of user IDs
Not writable from this tool:
formula, rollup, unique_id, created_time, last_edited_time, created_by, last_edited_by: computed by Notion
files, verification, place, location, button: not supported for value writes here
Inputs: page_id (required), properties (required).
update_data_sourceA
CRITICAL: full-list semantics. When you update a select or status property's options array, you MUST send the full desired list. Any existing option you omit will be permanently removed from the database, along with any relationship to rows currently using it. Rows that currently reference a removed option are silently reassigned to the default group's first option (for example "Not started" for status properties). No signal is raised. If you want to preserve the meaning of existing rows when removing an option, reclassify those rows to another explicit option before removing the option from the schema. To add one option, first call get_database, then resend the full current list with your addition appended.
Cannot toggle is_inline on existing databases. is_inline is a database-level field, not a data-source field. A separate update_database tool may be added later.
Updates a database's schema: rename properties, add or update property definitions, remove properties, change the title, or move it to/from trash. Use after get_database. Supports raw Notion payloads and schema helper payloads; read resource easy-notion://docs/update-data-source for modes, examples, status notes, and limitations. At least one of title, properties, or in_trash must be provided.
Inputs: title, page_id, in_trash, properties, +1 more.
update_pageA
Update page title, icon, or cover. Cover accepts an image URL, or a file:// path (stdio transport only) which will be uploaded to Notion. In HTTP transport, the file:// form is rejected — use an HTTPS URL instead.
Inputs: page_id (required), icon, cover, title.
update_sectionA
DESTRUCTIVE, no rollback: this tool deletes blocks in the section, then writes new blocks. If the write fails mid-call, the section is left partially or fully emptied; for most sections the heading anchor is deleted, so a retry can fail with "heading not found." For irreplaceable sections, duplicate_page the target first so you have a restore point.
Update a section of a page by heading name. Finds the heading, replaces everything from that heading to the next section boundary. For H1 headings, the section extends to the next heading of any level. For H2/H3 headings, it extends to the next heading of the same or higher level. Include the heading itself in the markdown. If the section starts at the first block, the replacement markdown must start with the same heading type so following sections stay in place. With preserve_heading:true, the existing heading block ID, text, type, comments, and toggleable state are preserved, but the section body blocks and existing toggleable-heading children are still destructively replaced; replacement markdown is treated as body-only, and a leading matching heading is stripped for compatibility. More efficient than replace_content for editing one section of a large page. Page mentions: @Title. Returns { deleted, appended }, plus deleted_blocks for the deleted top-level blocks when present and block_map for the top-level appended blocks when present. A dry run instead returns { success: true, dry_run: true, operation, page_id, heading, target_block_id, target_block_type, preserve_heading, deleted, appended, would_delete_block_ids, append_parent_id }, plus append_after_block_id when the append is anchored to a preceding block, and would_update with would_update_block_id when the heading block itself is rewritten.
Inputs: heading (required), page_id (required), markdown (required), dry_run, +3 more.
update_toggleA
DESTRUCTIVE, no rollback: this tool preserves the matched toggle container block ID, then deletes its body children and appends replacement body blocks. Child block IDs inside the body change, and if the write fails mid-call the toggle can be left partially or fully emptied. For irreplaceable content, duplicate_page the target first so you have a restore point.
Update the body of one toggle by title from a page. Searches recursively and matches plain toggle blocks plus toggleable heading_1, heading_2, and heading_3 blocks using case-insensitive trimmed text. The markdown is replacement body content, not a wrapper that renames the toggle, and the server converts it into native Notion blocks, not flat/plain text. The server automatically handles Notion API limits: batches more than 100 child blocks, splits rich text over 2000 characters, and writes deeply nested blocks in additional passes, so callers can send a full multi-section toggle tree in one call with no need to pre-chunk or pre-split. If the markdown parses as one matching top-level toggle or toggleable heading wrapper, that wrapper is ignored and only its children are used as the replacement body. For supported markdown syntax, read resource easy-notion://docs/markdown. Page mentions: @Title. Returns: { success: true, block_id, type, deleted, appended }, where deleted and appended are counts, plus deleted_blocks for the deleted top-level body blocks when present and block_map for the top-level appended body blocks when present. A dry run instead returns { success: true, dry_run: true, operation, page_id, title, block_id, type, deleted, appended, would_delete_block_ids, append_parent_id }.
Inputs: title (required), page_id (required), markdown (required), dry_run, +2 more.
update_viewA
Update a Notion database view. Pass at least one update field. Null filter, sorts, or quick_filters values are forwarded to clear those fields.
Inputs: view_id (required), name, sorts, filter, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 43 tools
Most tools are clearly distinct by resource (page, block, toggle, database, view, comment, user). Some potential confusion exists between update_section/update_toggle/update_block and read_section/read_block/read_toggle, but descriptions clarify the target granularity. The pair add_database_entry/add_database_entries is intentionally similar but the plural is self-explanatory.
The set predominantly uses verb_noun naming (create_page, read_page, update_page, archive_page, restore_page, query_database, add_database_entry, delete_database_entry). Minor deviations exist: get_view vs list_views, get_database vs list_databases, and get_me/get_config don't follow the verb_noun pattern, but the overall convention is consistent and predictable.
43 tools is on the heavy side for a single MCP server, but the breadth roughly matches Notion's feature surface (pages, blocks, toggles, databases, views, comments, users). The count is justified by the domain, though it approaches the upper bound where navigation becomes burdensome.
The tool surface covers the full lifecycle for pages (create, read, update, archive, restore, duplicate, move), blocks (read, update, delete, append, replace), toggles (read, update, archive, restore), databases (create, get, list, query, update schema, add/update/delete entries), views (list, create, update, delete), comments, and users. Notable gaps like subpage deep-duplication and database inline toggling are explicitly documented as limitations rather than missing coverage.
Maintenance
Related MCP Connectors
Hosted Notion MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Related MCP Servers
- AlicenseAqualityAmaintenanceMarkdown-first MCP server for Notion that provides 7 composite action-based tools consolidating 28+ REST API endpoints, enabling AI agents to efficiently manage pages, databases, blocks, and content with automatic pagination and bulk operations.101,730 npm36Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that enables LLMs to interact with Notion workspaces via the Notion API, supporting page creation, database management, and content retrieval. It features markdown conversion to optimize token usage and enhanced error handling for more reliable workspace interactions.191MIT
- AlicenseAqualityDmaintenanceA lightweight Notion MCP server that minimizes token usage by returning Markdown instead of raw JSON, enabling efficient read/write operations on Notion pages.9MIT
- AlicenseNot gradedqualityDmaintenanceStateless MCP server exposing the full Notion API as 33 tools, enabling users to manage pages, databases, blocks, comments, users, and file uploads using their own integration token.Apache 2.0