Notion

通过 Maton 平台安全连接 Notion，支持查询、搜索与读取内容，写操作需用户确认。

已扫描

项目

内容

适合谁

需要自动化管理 Notion 内容的个人用户、希望集成 Notion 数据到工作流的开发者

不适合谁

无需与 Notion 交互的普通用户、无法访问网络或配置 API 密钥的环境

国内可用性

需网络配置。可能需要网络配置或第三方服务可访问。

安装难度

新手友好（★☆☆）。基于终端操作、依赖、API Key 和本地环境要求的初步判断。

安装与下载

复制命令安装

openclaw skills install @byungkyu/notion-api-skill

官方 ZIP下载官方 ZIP

Skill 说明

命令、参数、文件名以原文为准

Notion

通过托管的 OAuth 认证访问 Notion API。可查询数据库、搜索页面并读取工作区内容。所有写入操作（创建、更新或删除页面、块和数据库）必须在用户明确确认目标资源和连接后才能执行。

快速开始

CLI：

maton notion search 'meeting notes'

maton api '/notion/v1/search'

Python：

import urllib.request, os, json
data = json.dumps({'query': 'meeting notes'}).encode()
req = urllib.request.Request('https://api.maton.ai/notion/v1/search', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Notion-Version', '2025-09-03')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))

基础 URL

https://api.maton.ai/notion/{native-api-path}

Maton 将请求代理至 api.notion.com，并自动注入您的 OAuth Token。写入操作（POST、PATCH、DELETE）仅可在用户确认目标页面/数据库 ID 及连接后执行。

必需请求头

所有 Notion API 请求均需包含版本头：

Notion-Version: 2025-09-03

安装

NPM：

npm install -g @maton/cli

Homebrew：

brew install maton-ai/cli/maton

认证

CLI：

maton login                          # 打开浏览器获取 API 密钥
maton login --interactive            # 跳过浏览器，直接粘贴 API 密钥
maton whoami                         # 查看当前认证状态

手动方式：

访问 [maton.ai](https://maton.ai) 注册或登录账户
进入 [maton.ai/settings](https://maton.ai/settings)
复制您的 API 密钥
将 API 密钥设置为环境变量 MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

连接管理

在 https://api.maton.ai 管理您的 Notion OAuth 连接。

列出连接

CLI：

maton connection list notion --status ACTIVE

maton api -X GET /connections -f app=notion -f status=ACTIVE

Python：

import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=notion&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))

创建连接

CLI：

maton connection create notion

maton api /connections -f app=notion

Python：

import urllib.request, os, json
data = json.dumps({'app': 'notion'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))

获取连接

CLI：

maton connection view {connection_id}

maton api /connections/{connection_id}

Python：

import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))

响应示例：

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "notion",
    "method": "OAUTH2",
    "metadata": {}
  }
}

请在浏览器中打开返回的 url 完成 OAuth 授权流程。

删除连接

CLI：

maton connection delete {connection_id}

maton api -X DELETE /connections/{connection_id}

Python：

import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))

指定连接

若您拥有多个 Notion 连接，需明确指定使用哪一个：

CLI：

maton notion search 'meeting notes' --connection {connection_id}

maton api /notion/v1/search --connection {connection_id}

Python：

import urllib.request, os, json
data = json.dumps({'query': 'meeting notes'}).encode()
req = urllib.request.Request('https://api.maton.ai/notion/v1/search', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Notion-Version', '2025-09-03')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))

若存在多个连接，始终指定连接以确保请求发送至正确的账户。

核心概念：数据库 vs 数据源

在 API 版本 2025-09-03 中，数据库与数据源是独立的概念：

概念	用途
数据库	创建数据库、获取数据源 ID
数据源	查询、更新模式、修改属性

使用 GET /databases/{id} 获取 data_sources 数组，然后调用 /data_sources/ 接口：

{
  "object": "database",
  "id": "abc123",
  "data_sources": [
    {"id": "def456", "name": "My Database"}
  ]
}

安全与权限

权限范围限定于已连接 Notion 账户内的页面、数据库、块、用户及搜索结果。
所有写入操作需用户明确批准。执行任何创建、更新或删除操作前：

1. 与用户确认目标资源（页面 ID、数据库 ID、块 ID）；

2. 在存在多个连接时验证正确的连接 ID；

3. 明确说明操作是否可逆或具有破坏性。

高风险/不可逆操作（需格外谨慎）：

- 删除页面或块（虽为归档而非永久删除，但可能影响工作流）

- 对多个页面或数据库进行批量更新

- 修改对团队成员可见的共享工作区页面

作用域边界：

- 仅操作用户明确命名或识别的页面与数据库，不得枚举或修改任务上下文外的资源。

- 使用任务所需的最小权限连接。

- 未经用户明确批准，不得执行批量或批处理操作。

API 参考

搜索

搜索页面：

POST /notion/v1/search
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "query": "meeting notes",
  "filter": {"property": "object", "value": "page"}
}

示例：

maton notion search 'meeting notes' --filter page

搜索数据源：

POST /notion/v1/search
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "filter": {"property": "object", "value": "data_source"}
}

示例：

maton notion search --filter data_source

数据源

获取数据源

GET /notion/v1/data_sources/{dataSourceId}
Notion-Version: 2025-09-03

示例：

maton notion data-source view <dataSourceId>

查询数据源

POST /notion/v1/data_sources/{dataSourceId}/query
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "filter": {
    "property": "Status",
    "select": {"equals": "Active"}
  },
  "sorts": [
    {"property": "Created", "direction": "descending"}
  ],
  "page_size": 100
}

示例：

maton notion data-source query <dataSourceId> \
  --filter '{"property":"Status","select":{"equals":"Active"}}' \
  --sorts '[{"property":"Created","direction":"descending"}]' \
  --page-size 100

更新数据源

PATCH /notion/v1/data_sources/{dataSourceId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "title": [{"type": "text", "text": {"content": "Updated Title"}}],
  "properties": {
    "NewColumn": {"rich_text": {}}
  }
}

示例：

maton notion data-source update <dataSourceId> \
  --body '{"title":[{"type":"text","text":{"content":"Updated Title"}}],"properties":{"NewColumn":{"rich_text":{}}}}'

数据库

获取数据库

GET /notion/v1/databases/{databaseId}
Notion-Version: 2025-09-03

示例：

maton notion database view <databaseId>

创建数据库

POST /notion/v1/databases
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "parent": {"type": "page_id", "page_id": "PARENT_PAGE_ID"},
  "title": [{"type": "text", "text": {"content": "New Database"}}],
  "properties": {
    "Name": {"title": {}}
  }
}

示例：

maton notion database create --parent-page PARENT_PAGE_ID --title 'New Database'

在 API 版本 2025-09-03 中，POST /databases 仅接受 title 属性——properties 中的其他字段将被静默忽略。如需定义模式，请使用创建返回的 data_sources[0].id 调用 PATCH /data_sources/{dataSourceId}（参见 [更新数据源](#update-data-source)）。

页面

获取页面

GET /notion/v1/pages/{pageId}
Notion-Version: 2025-09-03

示例：

maton notion page view <pageId>

创建页面

POST /notion/v1/pages
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "parent": {"page_id": "PARENT_PAGE_ID"},
  "properties": {
    "title": {"title": [{"text": {"content": "New Page"}}]}
  }
}

示例：

maton notion page create --parent-page PARENT_PAGE_ID --title 'New Page'

在数据源中创建页面

POST /notion/v1/pages
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "parent": {"data_source_id": "DATA_SOURCE_ID"},
  "properties": {
    "Name": {"title": [{"text": {"content": "New Page"}}]},
    "Status": {"select": {"name": "Active"}}
  }
}

示例：

maton notion page create --data-source DATA_SOURCE_ID --title 'New Page' \
  --properties '{"Status":{"select":{"name":"Active"}}}'

更新页面属性

PATCH /notion/v1/pages/{pageId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "properties": {
    "Status": {"select": {"name": "Done"}}
  }
}

示例：

maton notion page update {pageId} --properties '{"Status":{"select":{"name":"Done"}}}'

更新页面图标

PATCH /notion/v1/pages/{pageId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "icon": {"type": "emoji", "emoji": "🚀"}
}

示例：

maton notion page update {pageId} --icon 🚀

或使用图片 URL：

maton notion page update {pageId} --icon https://example.com/icon.png

归档页面

PATCH /notion/v1/pages/{pageId}
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "archived": true
}

示例：

maton notion page archive {pageId}

块

获取块子项

GET /notion/v1/blocks/{blockId}/children
Notion-Version: 2025-09-03

示例：

maton notion block children <blockId>

追加块子项

PATCH /notion/v1/blocks/{blockId}/children
Content-Type: application/json
Notion-Version: 2025-09-03

{
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [{"type": "text", "text": {"content": "New paragraph"}}]
      }
    }
  ]
}

示例：

maton notion block append <blockId> \
  --children '[{"object":"block","type":"paragraph","paragraph":{"rich_text":[{"type":"text","text":{"content":"New paragraph"}}]}}]'

删除块

DELETE /notion/v1/blocks/{blockId}
Notion-Version: 2025-09-03

示例：

maton notion block delete <blockId>

用户

列出用户

GET /notion/v1/users
Notion-Version: 2025-09-03

示例：

maton notion user list

获取当前用户

GET /notion/v1/users/me
Notion-Version: 2025-09-03

示例：

maton notion whoami

过滤操作符

equals, does_not_equal
contains, does_not_contain
starts_with, ends_with
is_empty, is_not_empty
greater_than, less_than

块类型

paragraph, heading_1, heading_2, heading_3
bulleted_list_item, numbered_list_item
to_do, code, quote, divider

分页

Notion 使用基于游标的分页。CLI 会自动处理分页，使用 --paginate 参数。

示例：

maton notion data-source query <dataSourceId> --paginate

代码示例

CLI

# 搜索匹配查询的页面
maton notion search 'roadmap'

# 查看特定页面
maton notion page view 0123456789abcdef0123456789abcdef

# 使用过滤器查询数据源
maton notion data-source query <dataSourceId> --filter '{"property":"Status","select":{"equals":"Active"}}'

# 使用 jq 过滤 —— 例如仅保留页面（响应包裹在 {"results": [...]} 中）
# 注意：--jq 需配合 --json 使用
maton notion search 'roadmap' --json --jq '.results | map(select(.object == "page"))'

JavaScript

const response = await fetch('https://api.maton.ai/notion/v1/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
    'Notion-Version': '2025-09-03'
  },
  body: JSON.stringify({ query: 'meeting' })
});

Python

import os
import requests

response = requests.post(
    'https://api.maton.ai/notion/v1/search',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Notion-Version': '2025-09-03'
    },
    json={'query': 'meeting'}
)

注意事项

所有 ID 均为 UUID（含或不含连字符）
使用 GET /databases/{id} 获取 data_sources 数组以获取数据源 ID
创建数据库需使用 POST /databases 接口
删除块后返回的块对象中 archived 字段为 true
重要：使用 curl 命令时，若 URL 包含方括号（如 fields[]、sort[]、records[]），请使用 curl -g 以禁用通配符解析
重要：当将 curl 输出管道至 jq 等命令时，部分 shell 环境中环境变量如 $MATON_API_KEY 可能无法正确展开。可能导致“无效 API 密钥”错误

错误处理

状态码	含义
400	缺少 Notion 连接
401	无效或缺失的 Maton API 密钥
429	速率限制（每账户 10 次/秒）
4xx/5xx	透传自 Notion API 的错误

故障排查：API 密钥问题

CLI：

检查认证状态：

maton whoami

通过列出连接验证 API 密钥有效性：

maton connection list

手动方式：

检查 MATON_API_KEY 环境变量是否已设置：

echo $MATON_API_KEY

通过列出连接验证 API 密钥有效性：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

@byungkyu

已收录 2 个 Skill

Notion

安装与下载

Skill 说明

Notion

快速开始

基础 URL

必需请求头

安装

认证

连接管理

列出连接

创建连接

获取连接

删除连接

指定连接

核心概念：数据库 vs 数据源

安全与权限

API 参考

搜索

数据源

获取数据源

查询数据源

更新数据源

数据库

获取数据库

创建数据库

页面

获取页面

创建页面

在数据源中创建页面

更新页面属性

更新页面图标

归档页面

块

获取块子项

追加块子项

删除块

用户

列出用户

获取当前用户

过滤操作符

块类型

分页

代码示例

CLI

JavaScript

Python

注意事项

错误处理

故障排查：API 密钥问题

相关推荐

enterprise-artifact-search

read-gbk

Read Microsoft Word documents (.docx and .doc) with Chinese support