better-notion

better-mcp-notion

Japanese / 日本語

一个 MCP 服务，让你只需使用一份 Markdown 文档即可操作 Notion。

现有的 Notion MCP 服务只是单薄的 API 封装，完成一项操作需要多次往返调用。better-mcp-notion 使用一份 Markdown 文档（YAML frontmatter + 正文），即可通过一次调用读取、创建和更新页面。

为什么选择 better-mcp-notion？

	传统 Notion MCP	better-mcp-notion
工具	16-22 个工具	9 个工具
创建数据库条目	3 次以上调用（搜索数据库、获取架构、创建页面、追加区块）	1 次调用
编辑页面	4 次以上调用（获取页面、获取区块、删除区块、追加区块）	1 次调用（读取、编辑、写入）
格式	原始 JSON 区块	Markdown
上下文窗口	开销大（工具定义 + JSON）	开销小

工具

工具	描述
read	将 Notion 页面读取为带 frontmatter 的 Markdown。支持通过 depth 递归读取子页面。
write	根据 Markdown 创建或更新页面。支持批量操作以及追加/前置内容。
search	按关键词搜索工作区。返回 Markdown 格式的列表。
list	将数据库记录列为表格，或将子页面列为列表。支持自然语言筛选和排序。
update	快速更新属性，无需重写内容。只需传入页面和键值对。
schema	查看或修改数据库架构——添加、移除或重命名列。
comment	添加或读取页面评论。
delete	归档（软删除）页面。
move	将页面移动到其他父页面或数据库。

快速开始

1. 创建 Notion 集成

1. 前往 notion.so/profile/integrations 并创建新的集成
2. 复制 API 密钥（ntn_...）
3. 将你要访问的页面/数据库分享给该集成（在页面菜单中选择“Connect to”）

2. 添加到 MCP 客户端

Claude Code

claude mcp add better-notion -- npx better-mcp-notion

然后设置环境变量：

export NOTION_API_KEY=ntn_your_api_key_here

Claude Desktop / Cursor / Windsurf

将以下内容添加到 MCP 配置文件中（例如 claude_desktop_config.json、.cursor/mcp.json）：

{
  "mcpServers": {
    "better-notion": {
      "command": "npx",
      "args": ["-y", "better-mcp-notion"],
      "env": {
        "NOTION_API_KEY": "ntn_your_api_key_here"
      }
    }
  }
}

从源码安装

git clone https://github.com/ai-aviate/better-mcp-notion.git
cd better-mcp-notion
npm install && npm run build

然后将 MCP 配置指向 node /path/to/better-mcp-notion/build/index.js。

用法

读取页面

read({ page: "https://notion.so/My-Page-abc123def456" })

返回：

---
id: abc123-def456
title: My Page
database: task-db-id
properties:
  Status: In Progress
  Tags:
    - backend
---
## Notes
- Completed API design

创建页面

write({ markdown: `
---
title: Meeting Notes
parent: "Project Alpha"
icon: "📝"
---
## Agenda
- Review progress
- Discuss next steps
` })

创建数据库条目

write({ markdown: `
---
title: Fix login bug
database: "Task Board"
properties:
  Status: In Progress
  Tags:
    - backend
    - urgent
  Due Date: "2026-03-01"
---
## Description
Login fails when password contains special chars.
` })

更新页面（编辑 read 的输出）

write({ markdown: `
---
id: abc123-def456
title: Updated Title
properties:
  Status: Done
---
## New content
Body replaces all existing blocks.
` })

向现有页面追加内容

使用 position: "append" 可在末尾添加内容，而无需重写整个页面。 只需提供新增内容——现有内容会保留。

write({ markdown: `
---
id: abc123-def456
---
## New section
This is added to the end of the page.
`, position: "append" })

position: "prepend" 则会在开头添加内容。

批量创建（一次调用创建多个页面）

使用 === 分隔页面：

write({ markdown: `
---
title: Task 1
database: "Task Board"
properties:
  Status: Todo
---
Task 1 details
===
---
title: Task 2
database: "Task Board"
properties:
  Status: Todo
---
Task 2 details
` })

使用筛选条件查询数据库

list({
  target: "Task Board",
  filter: "Status is Done AND Priority is High",
  sort: "Due Date ascending"
})

筛选语法

• Status is Done / Status = Done - 等于
• Priority != Low - 不等于
• Tags contains backend - 多选包含
• Done is true - 复选框
• Score > 80 - 数值比较（>、<、>=、<=）
• Due Date after 2026-03-01 - 日期晚于/早于
• 使用 AND 组合：Status is Done AND Priority is High

排序语法

• Due Date ascending 或 Due Date asc
• Created descending 或 Created desc

读取页面及其子页面

read({ page: "parent-page-id", depth: 2 })

depth: 1 = 仅当前页面（默认），2 = 包含子页面，3 = 包含孙级页面。

快速更新属性

无需重写内容即可更新属性：

update({ page: "My Task", properties: { "Status": "Done", "Priority": "High" } })

管理数据库架构

// View schema
schema({ database: "Task Board" })

// Add a column
schema({ database: "Task Board", action: "add", property: "Priority", type: "select", options: ["Low", "Medium", "High"] })

// Rename a column
schema({ database: "Task Board", action: "rename", property: "Due", name: "Due Date" })

// Remove a column
schema({ database: "Task Board", action: "remove", property: "Old Column" })

评论

// Read comments
comment({ page: "abc123" })

// Add a comment
comment({ page: "abc123", body: "Looks good! Ready to ship." })

Frontmatter 参考

写入（创建/更新）

字段	创建	更新	说明
id	-	必填	要更新的页面 ID
title	建议填写	可选	页面标题
parent	必填*	忽略	父页面名称或 ID
database	必填*	忽略	数据库名称或 ID（*parent 和 database 二选一）
icon	可选	可选	表情符号或图片 URL
cover	可选	可选	封面图片 URL
properties	可选	可选	数据库属性（与架构匹配）

读取（仅输出）

字段	说明
id	页面 UUID
url	Notion 页面 URL
title	页面标题
parent / database	父页面或数据库 ID
icon、cover	表情符号或图片 URL
properties	所有数据库属性
created、last_edited	时间戳（只读）

传入 write 时，只读字段（url、created、last_edited、公式等）会被安全忽略。

开发

npm run dev          # TypeScript watch mode
npm test             # Run tests
npm run test:watch   # Test watch mode

许可证

Elastic License 2.0 (ELv2) — 可免费使用、修改和分发。不得将其作为托管服务提供。