AI导哈

Notion AI 助手连接服务

一个通过官方REST API将AI助手连接到Notion工作区的模型上下文协议（MCP）服务器，支持搜索、读取、创建和管理页面、数据库、块、评论和用户。

  • by roygabriel
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 roygabriel/mcp-notion

使用说明

MCP服务器概念

模型上下文协议（MCP）服务器，通过官方REST API将人工智能助手连接到Notion工作空间。搜索、阅读、创建和管理页面、数据库、块、评论和用户。

特性

  • 搜索与发现 --跨页面和数据库搜索，列出所有数据库
  • 页面管理 --获取、创建、更新、移动和删除具有完整属性支持的页面
  • 数据库操作 --使用复杂的过滤器进行查询，创建和更新数据库模式
  • 区块管理 --读取、追加、更新和删除内容块
  • 评论 --在页面和区块上阅读和创建评论
  • 用户管理 --列出工作区用户，获取用户详细信息
  • 辅助工具 --使用类似markdown的语法简化页面创建
  • 批量操作 --创建、更新或删除多个具有速率限制的页面
  • 模板 --从内置模板（会议笔记、每日日志等）创建页面
  • 出口 --将页面导出为Markdown，将数据库导出为CSV
  • 智能查询 --最近编辑的页面、任务查找器、关系追随者
  • 交叉平台的 --Linux、macOS和Windows

先决条件

安装

# Clone and build
git clone https://github.com/rgabriel/mcp-notion.git
cd mcp-notion
make build

# Or install directly
go install github.com/rgabriel/mcp-notion@latest

配置

变量 必填 默认 描述
NOTION_API_TOKEN 是 -- 来自的集成令牌 notion.so/my集成 （开始于 secret_)
NOTION_API_VERSION 没有 2022-06-28 通知API版本
NOTION_TIMEOUT 没有 30 HTTP请求超时（秒）

复制 .env.example 到 .env 地方发展：

cp .env.example .env
# Edit .env and set NOTION_API_TOKEN

重要提示： 您必须通过“…”菜单与集成共享每个页面/数据库→ Notion中的“添加连接”。没有这个，你会得到“找不到对象”错误。

使用Claude Desktop

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "notion": {
      "command": "/path/to/mcp-notion",
      "env": {
        "NOTION_API_TOKEN": "secret_your_token_here"
      }
    }
  }
}

配置文件位置：

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux： ~/.config/claude/claude_desktop_config.json
  • 窗户： %APPDATA%\Claude\claude_desktop_config.json

使用Claude代码

添加到您的 ~/.claude.json 或项目 .claude/settings.json:

{
  "mcpServers": {
    "notion": {
      "command": "/path/to/mcp-notion",
      "env": {
        "NOTION_API_TOKEN": "secret_your_token_here"
      }
    }
  }
}

或通过CLI启动：

NOTION_API_TOKEN="secret_..." claude --mcp-server "notion:/path/to/mcp-notion"

可用工具

搜索与发现

工具 说明 必需参数
search 在所有页面和数据库中搜索 --
list_databases 列出所有可访问的数据库 --
get_database 获取数据库详细信息，包括架构 database_id

页面

工具 说明 必需参数
get_page 获取页面元数据和属性 page_id
get_page_content 以块的形式获取页面内容 page_id
create_page 在数据库中或页面下创建页面 parent, properties
update_page 更新页面属性、图标或封面 page_id
move_page 将页面移动到新的父级 page_id, parent
delete_page 存档（删除）页面 page_id

数据库

工具 说明 必需参数
query_database 使用过滤器、排序、分页进行查询 database_id
create_database 创建新数据库 parent, title, properties
update_database 更新数据库标题、描述、架构 database_id

积木

工具 说明 必需参数
get_block 获取特定区块 block_id
get_block_children 获取块或页面的子块 block_id
append_blocks 将块附加到页面或块 block_id, children
update_block 更新块内容 block_id
delete_block 删除块及其子块 block_id

评论

工具 说明 必需参数
get_comments 获取页面或块上的评论 block_id 或 page_id
create_comment 创建评论或回复 parent, rich_text

用户

工具 说明 必需参数
list_users 列出所有工作区用户 --
get_user 获取用户详细信息 user_id
get_bot_user 获取当前机器人用户信息 --

辅助工具

工具 说明 必需参数
create_simple_page 创建一个包含markdown内容的页面 title
append_to_page 将markdown内容附加到页面 page_id, content
search_in_database 在特定数据库中搜索 database_id, query

批量操作

工具 说明 必需参数
batch_create_pages 创建多个页面 pages
batch_update_pages 更新多个页面 page_ids
batch_delete_pages 存档多个页面 page_ids

模板

工具 说明 必需参数
create_page_from_template 从模板创建页面 template_name, title
list_templates 列出可用模板 --

可用模板： meeting_notes, daily_log, project_brief, sprint_planning, retrospective

出口

工具 说明 必需参数
export_page_as_markdown 将页面导出为Markdown page_id
export_database_as_csv 将数据库导出为CSV database_id

智能查询

工具 说明 必需参数
get_recently_edited 获取最近编辑的页面 --
get_my_tasks 查找分配给机器人用户的任务 --
get_related_pages 关注页面关系 page_id

例子

"Search for all pages about project planning"

"Create a meeting notes page titled 'Team Sync - Feb 3' with sections for discussion and action items"

"Query the Tasks database for all items where Status is 'In Progress' and Priority is 'High'"

"Export the Q1 Planning page as Markdown with frontmatter"

"Show me pages I edited in the last 3 days"

发展

# Run tests
make test

# Run tests with coverage
make cover

# Lint
make lint

# Format code
make fmt

# Build with version
make build

# Run locally
NOTION_API_TOKEN="secret_..." make run

故障排除

“找不到对象”错误

页面/数据库尚未与您的集成共享。在Notion中打开它→ “…”菜单→ “添加连接”→ 选择您的集成。

认证失败

验证 NOTION_API_TOKEN 正确设置并以开头 secret_.再生时间 notion.so/my集成 如果需要的话。

UUID格式无效

从Notion URL中提取32个字符的ID。接受破折号和无破折号格式。

速率限制

服务器通过自动重试和指数回退强制执行3个请求/秒。批处理操作在请求之间增加了350毫秒的延迟。

超时错误

增加 NOTION_TIMEOUT （默认值：30秒）。请检查您的网络连接。

未找到房产

使用 get_database 查看确切的属性名称——它们区分大小写。

许可证

MIT许可证——见 许可证 了解详情。

相关 MCP