简单概念MCP
Markdown是第一个将AI代理连接到Notion的MCP服务器。
代理编写markdown-easy-notion-mcp将其转换为notion的块API并再次返回。
42种工具·24种区块类型·与官方Notion MCP相比代币减少92%·完全往返保真度```bash
npx easy-notion-mcp
**看看它在行动→** Live Notion页面完全通过easy concept mcp创建和管理。
______________________________________________________________________
## 易概念mcp与其他notion mcp服务器相比如何?
功能 · 简单概念mcp · 官方概念mcp(npm) · 更好的概念mcp
**内容格式** · ✅ 标准GFM降价 · ❌ 原始通知API JSON · ⚠️ Markdown(有限的块类型)
**块类型** · ✅ 24(切换、列、标注、方程式、嵌入、表格、文件上传、任务列表) · ⚠️ 全部(作为原始JSON) · ⚠️ ~7(标题、段落、列表、代码、引号、分隔符)
**往返保真度** · ✅ 完整--阅读标记、修改、回写 · ❌ 原始JSON需要块重建 · ⚠️ 不受支持的块会自动丢弃
**工具** · 42个单独命名的工具 · 18个由OpenAPI自动生成的 · 9个复合工具(39个动作)
**文件上传** · ✅ `file:///path` 在markdown中❌ 打开功能请求 · ✅ 5步生命周期
**快速注射防御** · ✅ 内容通知前缀+URL净化 · ❌ · ❌
**数据库条目格式** · 简单 `{"Status": "Done"}` 键值对 · 简化键值对 · 简单键值对
**身份验证选项** · API令牌或OAuth · nenenebb API令牌或OAth · nenenebc API令牌或OAauth
### 易概念mcp可以节省多少代币?
|操作|简单的概念mcp |更好的概念mcp|官方概念mcp |储蓄与官方|
|---|---|---|---|---|
|页面已读| **291个代币** | ⚠️ 236个代币|6536个代币| **95.5%** |
|数据库查询(5行)| **347代币** |704个代币|2983个代币| **88.4%** |
|搜索(3个结果)| **298代币** |347个代币|1824个代币| **83.7%** |
| **合计(加权)** | **936个代币** |1287个代币|11343个代币| **91.7%** |
⚠️ 更好的概念是mcp页面读取看起来更小,因为它们会默默地删除11种块类型(标注、切换、表、任务列表、方程、书签、嵌入)。在内容覆盖率相同的情况下,简单的概念是mcp更有效。
*通过针对相同的Notion内容运行所有三个MCP服务器并使用tiktoken cl100k_base计数令牌来衡量。保存原始响应以供验证。*
## 如何设置简单的概念mcp?
### 使用API令牌
创建一个 概念整合,复制令牌,与它共享您的页面。
**克劳德代码:**```bash
claude mcp add notion -s user \
-e NOTION_TOKEN=ntn_your_integration_token \
-- npx -y easy-notion-mcp
这将在您的Claude代码中注册服务器 用户级 config(-s user)并通过 NOTION_TOKEN 通过以下方式直接访问MCP子进程 -e。您的shell环境和rcfiles未受影响——令牌位于Claude Code的配置文件中,作用域到此服务器,其他进程不可见。为设置默认父页面 create_page,添加 -e NOTION_ROOT_PAGE_ID= 同一个命令。
OpenClaw:```bash
openclaw config set mcpServers.notion.command "npx"
openclaw config set mcpServers.notion.args '["-y","easy-notion-mcp"]'
然后在启动OpenClaw之前通过父shell环境提供令牌:```bash
export NOTION_TOKEN=ntn_your_integration_token
这 export 表单是继承父shell环境的任何MCP客户端的通用回退。警告:除非您将其添加到您的shell rcfile中,否则它只会在当前的shell会话中持续存在,这有其自身的安全隐患 -e 当具体使用Claude Code时,请参考上述表格。
克劳德桌面/光标/风帆 --添加到MCP配置文件中:```json
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "easy-notion-mcp"],
"env": {
"NOTION_TOKEN": "ntn_your_integration_token"
}
}
}
}
配置文件位置:Claude Desktop→ `claude_desktop_config.json` ·光标→ `.cursor/mcp.json` ·风帆冲浪→ `~/.windsurf/mcp.json`
VS Code Copilot — add to .vscode/mcp.json (uses servers not mcpServers)```json
{
"servers": {
"notion": {
"command": "npx",
"args": ["-y", "easy-notion-mcp"],
"env": {
"NOTION_TOKEN": "ntn_your_integration_token"
}
}
}
}
用于低上下文Notion访问的CLI配置文件
使用 easy-notion 当代理需要Notion访问而不加载完整的MCP工具界面时,或者当您希望为不同的权限模式进行单独的Notion集成时,可以使用CLI。个人资料在 ~/.config/easy-notion-mcp/profiles.json 默认情况下,引用环境变量名,而不是原始令牌。```bash
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
读取命令适用于只读配置文件:```bash
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"
修改命令需要一个读写配置文件:```bash
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将处理身份验证,而无需复制粘贴令牌。
**启动服务器:**```bash
npx -p easy-notion-mcp easy-notion-mcp-http
需要 NOTION_OAUTH_CLIENT_ID 和 NOTION_OAUTH_CLIENT_SECRET env变量。看 OAuth设置 在......下面
克劳德代码:```bash
claude mcp add notion --transport http http://localhost:3333/mcp
**OpenClaw:**```bash
openclaw config set mcpServers.notion.transport "http"
openclaw config set mcpServers.notion.url "http://localhost:3333/mcp"
克劳德桌面:
前往设置→ 连接器→ 添加自定义连接器,输入 http://localhost:3333/mcp.
您的浏览器将打开Notion的授权页面。选择要共享的页面,单击“允许”,完成。
Manual project-scoped install (advanced) — register easy-notion-mcp per-project by placing .mcp.json at your project root
如果你想注册 easy-notion-mcp 按项目而不是用户范围,将以下内容粘贴到 .mcp.json 文件在 你的 项目根:```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集成令牌和(可选)根页面ID。请注意,此文件应位于 **你的** 项目,不在此仓库中——Claude Code将自动注册它在项目范围内找到的任何服务器 `.mcp.json` 并尝试启动它,因此使用占位符凭据提交一个将在repo打开时导致“连接失败”。
**Dify/n8n/FlowiseAI** (基于Docker的平台):
在您的主机上运行HTTP服务器:```bash
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,并将承载添加到请求头中:```
http://host.docker.internal:3333/mcp
Authorization: Bearer
> **为什么不是localhost?** 这些平台通常在Docker中运行。 `localhost` 容器内部是指容器本身,而不是您的主机。 `host.docker.internal` 弥合差距。
>
> **HTTP主机和承载:** HTTP服务器绑定 `127.0.0.1` 默认情况下,静态令牌模式需要 `NOTION_MCP_BEARER`. `host.docker.internal` 到达主机的网桥IP,因此设置 `NOTION_MCP_BIND_HOST=0.0.0.0` 并在每个客户端请求时发送承载报头。OAuth模式(按用户发布承载)是共享Docker部署的替代方案。
简单的概念是mcp可以与任何兼容mcp的客户端一起使用。服务器通过stdio(API令牌模式)或HTTP(OAuth或API令牌模式)运行。
如果您在设置过程中遇到问题 不和谐社区 这是一个提问的好地方。这 `#easy-notion-mcp` 频道涵盖了设置和设计讨论。虫子还在继续 GitHub问题.
## 配置
### Stdio模式(API令牌)
|变量|必填|默认|描述|
|---|---|---|---|
| `NOTION_TOKEN` |是|-|通知API集成令牌|
| `NOTION_ROOT_PAGE_ID` |否|--|默认父页ID|
| `NOTION_TRUST_CONTENT` |没有| `false` |跳过降价阅读回复中的内容通知(`read_page`, `read_section`, `read_block`, `read_toggle`) |
> **关于 `.env` 文件(仅限贡献者):** 简单的概念mcp加载a `.env` 通过以下方式从当前工作目录中删除文件 `dotenv`在实践中,这意味着 `.env` 只有当您从克隆的仓库签出运行服务器时,才“正常工作”(`node dist/index.js` 之后 `npm install && npm run build`),因为repo根是您的cwd。它是 **不** 通过调用包时加载 `npx easy-notion-mcp` 或者从任意目录进行全局安装——这是标准的npm CLI行为。对于 `npx` 路径,通行证 `NOTION_TOKEN` 通过 `-e` 旗在 Claude代码设置 以上,或通过MCP客户端的配置 `env` 块。
### OAuth/HTTP传输
跑 `npx -p easy-notion-mcp easy-notion-mcp-http` 启动支持OAuth的HTTP服务器。
|变量|必填|默认|描述|
|---|---|---|---|
| `NOTION_OAUTH_CLIENT_ID` |是(OAuth模式)|--|注意公共集成OAuth客户端ID|
| `NOTION_OAUTH_CLIENT_SECRET` |是(OAuth模式)|--|注意公共集成OAuth客户端机密|
| `PORT` |没有| `3333` |HTTP服务器端口|
| `OAUTH_REDIRECT_URI` |没有| `http://localhost:{PORT}/callback` |OAuth回调URL|
| `NOTION_MCP_BIND_HOST` |没有| `127.0.0.1` |绑定地址。默认为环回;集 `0.0.0.0` 用于网络可达或特定接口,如 `192.168.1.5`. |
| `NOTION_MCP_BEARER` |是(静态令牌模式)|--|客户端在静态令牌HTTP模式下需要共享密钥承载。服务器拒绝在没有它的情况下启动。在OAuth模式下不需要。 |
要获取OAuth凭据,请创建 **公共融合** 在 notion.so/profile/集成 并配置 `http://localhost:3333/callback` 作为重定向URI。
在OAuth模式下, `create_page` 工作没有 `NOTION_ROOT_PAGE_ID` --默认情况下,页面是在用户的私有工作区部分创建的。
### HTTP模式安全态势
HTTP传输是为 **可信网络**:具有承载密钥的单运营商自托管,或用于共享部署的OAuth。它并没有因为直接接触开放的互联网而变得坚硬;如果需要远程访问,请在其前面放置一个带TLS的反向代理。
**静态令牌模式需要一个承载者。** 开始 `npx -p easy-notion-mcp easy-notion-mcp-http` 只有 `NOTION_TOKEN` 该组将拒绝开始。在服务器环境中设置共享密钥载体,然后配置MCP客户端将其作为 `Authorization: Bearer ` 在每一个 `/mcp` 请求:```bash
export NOTION_MCP_BEARER=$(openssl rand -hex 32)
NOTION_TOKEN=ntn_your_integration_token npx -p easy-notion-mcp easy-notion-mcp-http
持票人与 crypto.timingSafeEqual.丢失或错误的承载者 401 { "error": "invalid_token" }。通过使用新值重新启动服务器来旋转密钥。
默认绑定是环回。 服务器绑定 127.0.0.1 默认情况下,仅限本地进程。集 NOTION_MCP_BIND_HOST=0.0.0.0 暴露所有接口或特定的IP 192.168.1.5 揭露一个。无论约束如何,都需要持票人。
承载者永远是信任的边界。 DNS重新绑定保护未连接到 /mcp OAuth注册/令牌端点上的CORS(/register, /token, /revoke)是宽容的。将承载或OAuth的每用户承载视为网络和Notion工作区之间的唯一障碍。即使对于仅环回部署,也要保持设置。如果您需要将此服务器暴露在受信任的网络之外,请将其置于处理TLS和源代码检查的反向代理之后。
用于多用户/远程的OAuth模式。 OAuth有自己的每用户承载强制; NOTION_MCP_BEARER 在OAuth模式下不需要。对于共享部署,OAuth的每用户身份模型是正确的——静态令牌+承载用于单个运营商的自托管。
file:// 上传仅限于stdio。 Markdown传递给 create_page, append_content, replace_content, update_section,或 update_page.cover 随着 file:// 通过HTTP拒绝URL。对本地文件工作流使用stdio模式(create_page_from_file 也仅限stdio),或将文件托管在HTTPS URL并在标记中使用该URL。
为什么要先降价?
官方的Notion MCP npm包返回原始的API JSON-深度嵌套的块对象,每个块有大约120个元数据令牌。其他服务器转换为markdown,但只支持少数块类型,默默地删除标注、切换、表、方程等。
简单的概念是,mcp使用代理已经知道的标准GFM标记。没有什么新东西需要学习,没有自定义标记语法,也没有块对象需要构造。代理编写markdown,easy-notion-mcp处理到notion的块API的转换,并再次返回,保留24个块类型。
这意味着代理人可以 编辑现有内容.读取页面,获取markdown,修改字符串,将其写回。什么都没有丢失。代理编辑Notion页面的方式与编辑代码的方式相同——就像文本一样。
简单的概念mcp是如何工作的?
页面 --读写markdown:```javascript
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"
})
再读一遍——同样的标记也出来了:```javascript
read_page({ page_id: "..." })
``````json
{ "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.
数据库 --编写简单的键值对:```javascript
add_database_entry({
database_id: "...",
properties: { "Status": "Done", "Priority": "High", "Due": "2026-05-15", "Tags": ["v2", "launch"] }
})
没有属性类型对象,没有嵌套 `{ select: { name: "Done" } }` 包装纸。简单的概念是mcp在运行时获取数据库模式并自动转换。代理人通行证 `{ "Status": "Done" }`很简单,剩下的就由mcp来做了。
**错误告诉你如何修复它们。** 错误的标题名称会返回可用的标题。缺少的页面建议与集成共享。一个坏的过滤器告诉你打电话 `get_database` 第一。代理可以自我纠正,而无需向用户寻求帮助。
**复杂的内容奏效。** 在切换、混合内容类型的列(列表+代码块+块引号)、深度列表嵌套和完整的unicode(日语、中文、阿拉伯语、表情符号)中嵌套切换,所有这些都是干净的往返。 `update_section` 标题搜索不区分大小写,如果未找到,则返回可用标题。 `add_database_entries` 处理部分失败——成功和失败的条目分别返回,因此代理可以只重试失败。
## 易概念mcp提供了哪些工具?
简单概念mcp包括6个类别的42个单独命名的工具。工具描述保持安全关键行为的内联,并指向MCP资源以获取更长的参考资料,如markdown语法、警告形状、属性分页和 `update_data_source` 示例。
### 页面(20个工具)
|工具|说明|
|---|---|
| `create_page` |从markdown创建页面|
| `create_page_from_file` |从本地markdown文件创建页面(仅限stdio)|
| `read_page` |以markdown方式阅读页面|
| `read_section` |按标题名称阅读一节|
| `read_block` |按ID读取一个块,包括容器的嵌套子块|
| `read_toggle` |按标题阅读一个切换或可切换的标题|
| `search_in_page` |在页面或一个切换中搜索原始块文本|
| `append_content` |在页面上添加标记|
| `replace_content` |原子替换所有页面内容(保留匹配块的块ID)|
| `update_section` |按标题名称更新章节;可选标题保留正文替换(破坏性;对于不可替代的内容,请先复制页面)|
| `update_toggle` |按标题更新一个切换体(破坏性;保留切换容器ID)|
| `archive_toggle` |按标题存档一个切换或可切换的标题|
| `restore_toggle` |通过存档的块ID恢复存档的切换或可切换的标题|
| `find_replace` |查找和替换文本,保留文件|
| `update_block` |按ID更新单个块(保留深度链接和注释的块标识)|
| `update_page` |更新标题、图标或封面|
| `duplicate_page` |复制页面及其内容|
| `archive_page` |将页面移至回收站|
| `move_page` |将页面移动到新的父级|
| `restore_page` |还原已存档的页面|
破坏性工具支持 `dry_run: true` 作为飞行前的准备。试运行不会
上传或验证本地 `file://` markdown上传,因为这将创建
通知上传;使用HTTPS URL或对本地文件不进行模拟运行。
但它无法浮出水面 `unmatched_blocks` 或 `truncated` 领域
因为它不调用Notion的更新端点。
`restore_toggle` 有意基于ID:传递返回的存档块ID
通过 `archive_toggle`.Notion不会公开标题的存档子枚举
搜索或a `read_page include_archived` 工作流,因此按标题还原不是
可用。
### 导航(3个工具)
|工具|说明|
|---|---|
| `list_pages` |列出父级下的子页面|
| `search` |搜索页面和数据库|
| `share_page` |获取可共享的URL|
### 数据库(9个工具)
|工具|说明|
|---|---|
| `create_database` |使用类型化架构创建数据库|
| `update_data_source` |更新数据库架构(添加、重命名或删除属性;更改标题;回收或还原)|
| `get_database` |获取数据库架构、属性名称和选项|
| `list_databases` |列出集成可以访问的所有数据库|
| `query_database` |使用过滤器、排序或文本搜索进行查询|
| `add_database_entry` |使用简单的键值对添加行|
| `add_database_entries` |在一次调用中添加多行|
| `update_database_entry` |使用简单的键值对更新行|
| `delete_database_entry` |删除(存档)数据库条目|
> **数据库写入工具拒绝未知的属性名和不受支持的属性类型,并显示明确的错误,而不是默默地删除它们。** 呼叫 `get_database` 首先确认属性名称和类型。支持的写入属性类型: `title`, `rich_text`, `number`, `select`, `multi_select`, `date`, `checkbox`, `url`, `email`, `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"]`);空数组清除关系。
简单的概念mcp获取数据库模式,将值映射到notion的属性格式,并在代理传递简单的键值对时自动处理类型转换,如 `{ "Status": "Done" }`.架构缓存5分钟,以避免批处理操作期间的多余API调用。
### 视图(6工具)
|工具|说明|
|---|---|
| `list_views` |列出数据库或数据源的已保存视图|
| `get_view` |获取一个已保存视图的原始配置|
| `query_view` |通过已保存的视图查询条目|
| `create_view` |创建表格、列表、图板、日历、图库或时间线视图|
| `update_view` |重命名或更新已保存视图的原始筛选/排序/配置字段|
| `delete_view` |明确确认删除已保存的视图|
### 评论(2个工具)
|工具|说明|
|---|---|
| `list_comments` |在页面上列出评论|
| `add_comment` |向页面添加评论|
### 用户(2个工具)
|工具|说明|
|---|---|
| `list_users` |列出工作区用户|
| `get_me` |获取当前机器人用户|
## 哪些MCP资源可用?
支持MCP资源的客户可以按需阅读这些文档,而无需将所有参考资料加载到每个工具描述中:
|资源URI|内容|
|---|---|
| `easy-notion://docs/markdown` |支持页面写入和读取的markdown语法|
| `easy-notion://docs/warnings` |警告代码和响应形状|
| `easy-notion://docs/property-pagination` | `max_property_items` 长属性的行为|
| `easy-notion://docs/update-data-source` | `update_data_source` 有效载荷模式、示例和模式安全说明|
## easy-concept mcp支持哪些块类型?
easy-concept-mcp使用标准markdown语法支持24种notion块类型,该语法扩展了notion特定块的约定,如开关、列和标注。代理编写熟悉的markdown——简单的概念是mcp处理notion块格式的转换。
### 标准降价
语法 · Markdown
标题 · `# H1` `## H2` `### H3`
粗体、斜体、删除线 · `**bold**` `*italic*` `~~strike~~`
内联代码 · `` `code` ``
友情链接 · `text`
图片 · ``
项目符号列表 · `- item`
编号列表 · `1. item`
任务列表 · `- [ ] todo` / `- [x] done`
Blockquote · `> text`
代码块```` ```language ```` |
表 · 标准管道表语法
分流器 · `---`
### 特定概念语法
|块|语法|
|---|---|
|切换| `+++ Title` ... `+++` |
|列| `::: columns` / `::: column` ... `:::` |
|标注(注)| `> [!NOTE]` |
|标注(提示)| `> [!TIP]` |
|警告(警告)| `> [!WARNING]` |
|标注(重要)| `> [!IMPORTANT]` |
|标注(信息)| `> [!INFO]` |
|标注(成功)| `> [!SUCCESS]` |
|标注(错误)| `> [!ERROR]` |
|方程式| `$$expression$$` |
|目录| `[toc]` |
|嵌入| `embed` |
|书签|单独行上的裸露URL|
|文件上传(图片)| `` |
|文件上传(文件)| `name` |
## 我可以在不丢失格式的情况下阅读和重写页面吗?
对。往返保真度是易概念mcp的核心设计保证,而不是副作用。
你写的就是你读回来的。 `read_page` 返回与以下语法完全相同的markdown语法 `create_page` 接受——标题、列表、表格、标注、切换、列、方程式,所有这些。
当页面包含此服务器尚未表示的Notion块类型时,例如 `synced_block`, `child_database`, `child_page`,或 `link_to_page`, `read_page` 包括a `warnings` 带代码的字段 `omitted_block_types` 列出省略的块ID和类型。穿越低谷的往返之旅 `replace_content` 将删除这些块,因此警告可以让代理避免不安全的重写。
Notion AI会议笔记(已弃用 `transcription`)块呈现为包含标题、可选录制时间戳和 `## Summary` / `## Notes` 部分;成绩单仅包含在 `read_page include_transcript: true`这些渲染读取发出 `read_only_block_rendered` 警告标记往返将用普通块替换本地会议块。
简单的概念mcp使代理能够读取页面、修改markdown字符串并将其写回,而不会丢失格式、结构或内容。无格式转换。无块重建。代理编辑Notion页面的方式与编辑代码的方式相同——就像文本一样。
### find_replace和replace_content有什么区别?
easy-concept mcp为不同的用例提供了三种编辑策略:
- **`replace_content`** --用新的markdown替换页面上的所有内容。最适合完全重写。
- **`update_section`** --替换由标题名称标识的单个部分。默认情况下,替换标记包括标题并替换整个部分。通过 `preserve_heading: true` (或CLI `--preserve-heading`)保留现有的标题块ID、文本、类型、注释和可切换状态,同时仅破坏性地替换节体。
- **`find_replace`** --查找并替换页面上任何位置的特定文本,保留所有其他内容和附件。最适合手术编辑。
通过 `dry_run: true` 在MCP工具上,或 `--dry-run` 在CLI中,在破坏之前
当你想要飞行前的反应而不是突变时进行编辑。
## 易概念mcp如何处理数据库?
easy-concept-mcp提供了9个数据库工具,抽象出notion的复杂属性格式。代理传递简单的键值对,如 `{ "Status": "Done", "Priority": "High" }`;简单的概念mcp在运行时获取数据库模式,缓存5分钟,并自动转换为notion的属性格式。
easy-concept mcp支持通过以下方式创建和更新具有类型化模式的数据库、使用过滤器和排序进行查询以及批量操作 `add_database_entries` (一次调用中有多行)。
## 那么安全和及时注射呢?
简单的概念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:` 是允许的。
## 常见问题
### 易概念mcp与官方的notion mcp服务器有何不同?
官方的Notion MCP npm包(`@notionhq/notion-mcp-server`)是一个原始的API代理-它返回未修改的Notion JSON,每次操作花费大约90%的令牌。简单的概念mcp将所有内容转换为代理已经知道的标准GFM标记,支持24种具有往返保真度的块类型,并包括快速注入防御。Notion还提供了一个单独的托管远程MCP服务器(基于OAuth),该服务器使用基于自定义HTML标签的markdown格式——简单的概念是,MCP使用标准的markdown语法。
### 易概念MCP与哪些MCP客户端配合使用?
简单的概念mcp适用于任何兼容mcp的客户端,包括Claude Desktop、Claude Code、Cursor、VS Code Copilot、Windsurf和OpenClaw。它同时支持stdio传输(API令牌)和HTTP传输(OAuth)。看 安装说明 用于每个客户端的可复制粘贴配置。
### 易概念mcp支持文件上传吗?
对。简单的概念mcp支持使用 `file:///` 协议采用markdown语法。上传图片 `` 和文件 `name`.
### 简单的概念mcp处理嵌套和复杂的内容吗?
对。开关中的嵌套开关、具有混合内容类型的列(不同列中的列表、块引号和代码块)、嵌套项目符号和编号列表,以及完整的unicode支持,包括日语、中文、俄语、阿拉伯语和表情符号-所有四舍五入清晰。
### 简单的概念mcp处理批处理操作中的部分失败吗?
对。 `add_database_entries` 返回单独 `succeeded` 和 `failed` 阵列。如果一个条目未通过验证,其他条目仍将被创建。代理可以只重试失败,而无需重新发送整个批次。
## 社区
有一个社区Discord 不一致.gg/S8cghJSVBUThe `#easy-notion-mcp` 频道涵盖了设置问题和设计讨论,服务器的其余部分则开放给展示和讲述或一般对话。对于bug和具体功能请求, GitHub问题 保持规范频道。
## 贡献
问题和PR欢迎 GitHub.
## 许可证
麻省理工学院