Notion Agent

概念代理

](https://www.npmjs.com/package/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 
 --type heading_1 --text "Meeting Notes"
notion blocks append --block-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

______________________________________________________________________

全球旗帜

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

--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

notion databases query --database-id  \
  --filter '{"property":"Status","select":{"equals":"Done"}}' \
  --sorts '[{"property":"Created","direction":"descending"}]' \
  --page-size 50 --flat --pretty

pages

# Get page as Markdown — best for agents reading content
notion pages markdown --page-id 

blocks

# Append different block types
notion blocks append --block-id  --type paragraph --text "Some text"
notion blocks append --block-id  --type code --text "console.log('hi')" --language typescript
notion blocks append --block-id  --type divider
notion blocks append --block-id  --blocks '[{"object":"block","type":"paragraph","paragraph":{"rich_text":[{"type":"text","text":{"content":"Hello"}}]}}]'

users

comments

search

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

workspace

______________________________________________________________________

输出

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工具使用 _:

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 错误），增加批量操作之间的延迟。

______________________________________________________________________

贡献

欢迎在 .

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

______________________________________________________________________

许可证

麻省理工学院--