AI导哈

Notion API代理工具

为AI代理和自动化脚本设计的Notion API命令行工具和MCP服务器，提供对Notion工作空间的程序化读写和查询功能。

  • by bcharleson
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 bcharleson/notion-agent

使用说明

概念代理

Notion API的代理本地CLI+MCP服务器。每个Notion端点都是一个CLI命令和一个MCP工具——一个集成，两个接口，零重复。

专为需要以编程方式读取、写入和查询Notion工作区的AI代理（Claude、Cursor、OpenClaw）和自动化脚本而构建。

安装

npm install -g notion-agent

或者在不安装的情况下运行：

npx notion-agent databases list

认证

您需要一个Notion集成令牌。创建一个 notion.so/my集成.

令牌格式： 令牌以开头 secret_ （较旧的集成）或 ntn_ （较新的集成）。两者都得到了支持。

选项1——环境变量（建议用于CI/CD代理）：

export NOTION_TOKEN=ntn_xxxxxxxxxxxx

选项2——交互式登录（保存到 ~/.notion-cli/config.json):

notion login
# Prompts: Paste your Notion integration token (secret_... or ntn_...):

选项3——每个命令标志：

notion --token ntn_xxxxxxxxxxxx databases list

重要提示： 您的集成只看到与其显式共享的页面和数据库。在Notion中，打开一个页面/数据库→ 分享 → 邀请 → 搜索您的集成名称。

快速开始

# Verify auth + show workspace
notion workspace info

# List accessible databases
notion databases list --pretty

# Search pages by title
notion search pages --query "Project Brief"

# Query a database with filter
notion databases query \
  --database-id abc123 \
  --filter '{"property":"Status","select":{"equals":"In Progress"}}' \
  --flat --pretty

# Get a page as Markdown (great for agents)
notion pages markdown --page-id abc123

# Append a block to a page
notion blocks append --block-id <page-id> --type heading_1 --text "Meeting Notes"
notion blocks append --block-id <page-id> --type to_do --text "Follow up with client" --checked false

# Create a page in a database
notion pages create \
  --parent-database-id abc123 \
  --title "New Task" \
  --pretty

全球旗帜

这些命令适用于每个命令：

标志 描述
--token <token> 以（权力）否决 NOTION_TOKEN 有人是。
--pretty 漂亮的打印JSON输出
--quiet 抑制输出（仅退出代码）
--fields <a,b,c> 仅返回指定的顶级字段
--flat 将页面属性值平铺为可读标量

--flat 旗帜

Notion将属性作为深度嵌套的对象返回。 --flat 将它们转换为人类可读的标量：

# Without --flat: {"Name": {"type":"title","title":[{"plain_text":"My Task",...}]}}
# With --flat:    {"Name": "My Task"}
notion databases query --database-id abc123 --flat --pretty

命令

databases

子命令 描述
list 列出所有可访问的数据库
get 获取数据库元数据和属性架构
schema 人类可读的模式——属性名、类型和选项
properties 物业名称和类型的简单列表
query 使用筛选器和排序查询数据库行
create 在父页面下创建新数据库
update 更新标题、描述或存档数据库 
notion databases query --database-id <id> \
  --filter '{"property":"Status","select":{"equals":"Done"}}' \
  --sorts '[{"property":"Created","direction":"descending"}]' \
  --page-size 50 --flat --pretty

pages

子命令 描述
get 检索页面及其属性
create 创建页面（子页面或数据库行）
update 更新页面属性
archive 将页面移至回收站
restore 从回收站还原页面
property 获取单个属性（用于>25个引用）
content 以块的形式获取页面内容
markdown 以Markdown文本形式获取页面内容 
# Get page as Markdown — best for agents reading content
notion pages markdown --page-id <id>

blocks

子命令 描述
get 检索单个块
children 列出封锁儿童（一级深度）
append 将块附加到页面或块
update 更新块内容
delete 删除块（从Notion可逆） 
# Append different block types
notion blocks append --block-id <id> --type paragraph --text "Some text"
notion blocks append --block-id <id> --type code --text "console.log('hi')" --language typescript
notion blocks append --block-id <id> --type divider
notion blocks append --block-id <id> --blocks '[{"object":"block","type":"paragraph","paragraph":{"rich_text":[{"type":"text","text":{"content":"Hello"}}]}}]'

users

子命令 描述
list 列出所有工作区成员
get 通过ID获取特定用户
me 获取此集成的机器人用户

comments

子命令 描述
list 在页面或块上列出评论
create 向页面或讨论线程添加评论

search

子命令 描述
all 按标题搜索页面和数据库
pages 仅搜索页面
databases 仅搜索数据库

注意：Notion搜索匹配 仅标题，而不是页面正文内容。

workspace

子命令 描述
info 验证auth+显示工作区名称和机器人身份

输出

stdout上的所有输出都是JSON。错误将转到stderr。退出码 0 =成功， 1 =错误。

# Machine-readable (default)
notion databases list

# Human-readable
notion databases list --pretty

# Pipe to jq
notion databases query --database-id abc123 --flat | jq '.results[] | .properties.Name'

MCP服务器

使用Claude Code、Claude Desktop、Cursor或任何MCP客户端作为MCP服务器。

克劳德代码

# Install globally first
npm install -g notion-agent

# Add as MCP server
claude mcp add notion -- notion-mcp

集 NOTION_TOKEN 在启动Claude Code之前，请在您的环境中执行以下操作，或将其内联传递：

NOTION_TOKEN=ntn_xxx claude

克劳德桌面

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "notion": {
      "command": "notion-mcp",
      "env": {
        "NOTION_TOKEN": "ntn_xxxxxxxxxxxx"
      }
    }
  }
}

光标

添加到光标MCP设置(~/.cursor/mcp.json):

{
  "mcpServers": {
    "notion": {
      "command": "notion-mcp",
      "env": {
        "NOTION_TOKEN": "ntn_xxxxxxxxxxxx"
      }
    }
  }
}

任何MCP客户端

MCP服务器在stdio上运行。从以下内容开始：

NOTION_TOKEN=ntn_xxx notion-mcp

可用的MCP工具

所有29个命令都可以作为具有命名约定的MCP工具使用 <group>_<subcommand>:

databases_list, databases_get, databases_schema, databases_properties, databases_query, databases_create, databases_update, pages_get, pages_create, pages_update, pages_archive, pages_restore, pages_property, pages_content, pages_markdown, blocks_get, blocks_children, blocks_append, blocks_update, blocks_delete, users_list, users_get, users_me, comments_list, comments_create, search_all, search_pages, search_databases, workspace_info

速率限制

概念强制执行 3个请求/秒 平均每次整合。该工具尊重这一点——如果你达到了速率限制(429 错误），增加批量操作之间的延迟。

贡献

欢迎在 github/bcharleson/notion-agent.

git clone https://github.com/bcharleson/notion-agent.git
cd notion-agent
npm install
npm run dev -- databases list --help   # run CLI in dev mode
npm run dev:mcp                         # run MCP server in dev mode
npm run build                           # compile to dist/
npm run typecheck                       # TypeScript check without build

许可证

麻省理工学院-- github/bcharleson/notion-agent

相关 MCP