⚡ fastNotion MCP

极智 Notion 连接器：让 AI 助手拥有“原生” Notion 操作超能力

fastNotion MCP 基于 fastMCP 打造，让你的 AI 助手（Trae/Cursor/Claude）真正“读懂”并“操作” Notion。

不用再手动复制粘贴 ID，不用担心 API 报错，它就像给你的 AI 装了一个 Notion 专用插件。

✨ 为什么它这么强？ (Superpowers)

Related MCP server: Notion MCP Server

💡 最佳实践 (Best Practices)

为了确保 AI 助手能最稳定地操作您的 Notion，请遵循以下建议：

1. 优先使用英文属性名：建议将数据库列名设为英文（如 Title, Status, Work Type, Date）。

2. 大小写与空格不敏感：代码会自动处理 Work Type、work_type 或 WorkType 之间的转换。

3. 保持必填项：确保 Title 属性（Notion 的唯一必填项）在数据库中存在。 | 开发者直供 | 小工具最怕没人维护，遇到 Bug 没人管。 | 作者深度自用，持续进化，Bug 发现即修复，体验永远保持在第一梯队。 |

🛠️ 部署流程 (Deployment Workflow)

请按照以下步骤在您的本地环境部署并激活服务：

1. 克隆项目与安装环境

首先，将项目克隆到本地并安装必要的依赖库：

# 克隆仓库 (请替换为您的实际 URL)
git clone https://github.com/whjwjx/notionMCP.git
cd notionMCP

# 安装核心依赖
pip install -r requirements.txt

2. 配置 Notion 凭证

在项目根目录创建 .env 文件（注意：此文件已在 .gitignore 中，不会被提交到仓库），用于存储您的私密配置：

# 必填：Notion 机器人 Integration Token
NOTION_TOKEN=your_integration_token_here

# 必填：目标数据库 ID
DATABASE_ID=your_database_id_here

💡 重要：

1. 请确保在 Notion 数据库设置中通过 Add connections 邀请了您的机器人。

2. 开源贡献者注意：如果您 Fork 本项目，请务必根据 .env.example 创建您自己的 .env 文件。不要在代码中硬编码任何 Token。

3. 本地验证与启动

在接入 IDE 前，建议手动运行脚本以确认环境与凭证无误：

python notion_mcp.py

若未提示错误（控制台保持静默即表示 stdio 传输已就绪），则说明配置成功。

4. IDE 接入 (以 Trae 为例)

方案 A：本地部署接入

如果您是在本地运行服务，请打开 Trae 的 MCP 设置（Settings -> MCP），添加如下 JSON 配置：

{
  "mcpServers": {
    "notion-mcp-local": {
      "command": "python",
      "args": ["<您的项目绝对路径>\\notion_mcp.py"],
      "workingDirectory": "<您的项目绝对路径>",
      "transport": "stdio"
    }
  }
}

注意：请将 <您的项目绝对路径> 替换为您本地克隆项目的实际路径。

方案 B：云端部署接入 (推荐)

如果您希望服务 24/7 在线，且无需在本地维护 Python 环境，推荐部署至 FastMCP Cloud。

详细部署步骤：

1. Fork 本仓库：点击页面右上角的 Fork 按钮，将项目保存到您的 GitHub 账号下。

2. 连接平台：

   • 登录 FastMCP Cloud 控制台。

   • 点击 Create New Server，授权并选择您刚才 Fork 的 notionMCP 仓库。

3. 配置环境变量 (Secrets)：

   • 在部署页面的 Environment Variables 区域，添加以下两个必填项：

     • NOTION_TOKEN: 您的 Notion Integration Token。

     • DATABASE_ID: 您的目标数据库 ID。

   • 注意：云端部署无需上传 .env 文件，直接在平台界面填写即可，更安全。

4. 设置启动入口 (Entrypoint)：

   • 在 Entrypoint 栏填写：notion_mcp.py:mcp（这将直接加载 MCP 对象，效率更高）。

5. 部署并获取接入信息：

   • 点击 Deploy。部署成功后，平台会为您生成唯一的 Server URL 和 Access Token。

6. 配置 Trae/IDE：

   • 将生成的 URL 和 Token 填入如下配置中：

{
  "mcpServers": {
    "notion-mcp-cloud": {
      "url": "https://your-app-name.fastmcp.app/mcp",
      "headers": {
        "Authorization": "Bearer fmcp_your_personal_access_token_here"
      }
    }
  }
}

💡 安全提示：云端部署后，任何人拥有该 URL 和 Token 都能操作您的 Notion。请务必妥善保管，不要将其泄露。

📖 使用指南 (Usage Examples)

您可以像和同事沟通一样，在 AI 对话框中下达指令。以下是核心功能的详细调用参考：

1. 数据库管理与探索

• 功能描述：获取数据库的元数据、结构、ID 以及数据源信息。

• 指令示例：帮我查一下 Notion 数据库 <您的数据库ID> 的结构信息

• 调用工具：get_database_info(database_id="...")

• 预期结果：返回数据库的 JSON 定义，包括标题（如“工作日志”）、创建时间及关联的数据源 ID。

2. 精准页面搜索

• 功能描述：在数据库内根据关键词或特定条件筛选页面。

• 指令示例：在数据库 <您的数据库ID> 中搜一下标题包含“测试”的页面

• 调用工具：query_database(database_id="...", filter_params={"property": "...", "title": {"contains": "测试"}})

• 预期结果：返回匹配的页面列表，包含页面 ID、标题摘要及访问链接。

3. 智能页面创建

• 功能描述：在指定数据库中自动关联数据源并创建新页面。

• 指令示例：在数据库 <您的数据库ID> 中新建页面，标题“今日代码提交”，内容“完成 MCP 接口封装”

• 调用工具：create_notion_page(database_id="...", title="...", content="...")

• 预期结果：在 Notion 中成功创建记录，并返回该页面的完整 URL 链接。

4. 动态属性更新

• 功能描述：通过页面 ID 快速更新现有页面的富文本属性内容。

• 指令示例：更新 Notion 页面 <您的页面ID> 的内容为“测试更新功能成功”

• 调用工具：update_notion_page(page_id="...", content="...")

• 预期结果：目标页面属性被即时修改，并返回更新后的页面跳转链接。

📂 项目架构 (Architecture)

.
├── notion_mcp.py    # 核心：MCP 服务入口与工具定义
├── notion_demo.py   # 底层：Notion API 请求封装引擎
├── requirements.txt # 依赖：项目运行环境清单
├── features.md      # 文档：全量功能支持手册
└── bug_fixes.md     # 记录：已知问题修复路线图

🛡️ 安全与合规 (Safety)

• 隐私第一：本项目严禁在代码中硬编码任何密钥。请务必妥善保管 .env 文件，避免提交至公开仓库。

• 权限最小化：建议仅为 Integration 开启必要的数据库访问权限，遵循最小授权原则。

🗺️ 未来路线图 (Roadmap)

🧱 内容深度管理 (Content Mastery)

• 动态属性识别：自动适配数据库 Schema，无需硬编码。

• 多版本 API 路由：智能兼容 Notion 不同时期的 API 特性。

• 块级（Blocks）深度读写：支持 AI 直接操作页面内的代码块、待办列表。

• 互动评论集成：在 IDE 内直接查看并回复 Notion 页面评论。

⚙️ 自动化工作流 (Workflow Automation)

• 任务状态自动流转：一键完成任务状态更新及时间戳记录。

• AI 自动化摘要：根据数据库变动自动生成日报/周报。

• 模板化一键建页：支持调用 Notion 数据库模板创建结构化内容。

🔍 搜索与导航 (Search & Navigation)

• 全局跨库搜索：突破单一数据库限制，实现全空间检索。

• 层级导航增强：让 AI 理解页面间的父子嵌套关系。