Notion MCP 服务器

Notion MCP 服务器 是一个模型上下文协议（MCP）服务器实现，使 AI 助手能够与 Notion 的 API 进行交互。这个生产就绪的服务器提供了一套完整的工具和端点，通过自然语言交互来读取、创建和修改 Notion 内容。

🚧 活跃开发中：数据库支持现已可用！评论和用户管理工具已添加。如果您觉得这个项目有用，请考虑给它一个星标 - 这让我知道这项工作对社区有价值，并激励进一步开发。

📑 目录

• 入门与集成
  • 设置流程
  • Cursor 集成
  • Claude 桌面集成
• 功能
• 文档
  • 可用工具
  • 可用资源
• 开发
• 技术细节
• 故障排除
• 贡献
• 许可证

🚀 入门与集成

设置流程

1. 获取 Notion API 密钥

   • 在 Notion 开发者 创建一个集成
   • 复制您的 API 密钥

2. 为您的页面启用集成

   • 在 Notion 中选择一个现有页面或创建一个新页面
   • 点击右上角的“...”菜单
   • 转到“连接”
   • 从列表中找到并启用您的集成

   

3. 选择您的集成方法

   • 根据您首选的 MCP 客户端，选择以下集成选项之一

4. 让您的 AI 助手与 Notion 交互

   • “创建一个包含今天任务的新页面”
   • “在 Notion 中更新我的会议记录”
   • “在我的会议记录页面中添加项目符号”
   • “创建一个用于跟踪项目的新数据库”
   • “在我的任务数据库中添加新条目”
   • “在我的项目页面中添加评论”
   • “显示此文档上的所有评论”
   • “列出我的工作区中的所有用户”
   • “获取特定用户的信息”

Cursor 集成

方法 1：使用 mcp.json

1. 在您的项目目录中创建或编辑 .cursor/mcp.json 文件：

{
  "mcpServers": {
    "notion-mcp-server": {
      "command": "env NOTION_TOKEN=YOUR_KEY NOTION_PAGE_ID=YOUR_PAGE_ID npx",
      "args": ["-y", "notion-mcp-server"]
    }
  }
}

2. 将 YOUR_KEY 和 YOUR_PAGE_ID 替换为您的实际 Notion API 密钥和页面 ID
3. 重新启动 Cursor 以应用更改

方法 2：手动模式

1. 打开 Cursor 并进入设置
2. 导航到“MCP”或“模型上下文协议”部分
3. 点击“添加服务器”或等效选项
4. 在相应字段中输入以下命令：

env NOTION_TOKEN=YOUR_KEY NOTION_PAGE_ID=YOUR_PAGE_ID npx -y notion-mcp-server

5. 将 YOUR_KEY 和 YOUR_PAGE_ID 替换为您的实际 Notion API 密钥和页面 ID
6. 保存设置并在必要时重新启动 Cursor

Claude 桌面集成

1. 在您的配置目录中创建或编辑 mcp.json 文件：

{
  "mcpServers": {
    "notion-mcp-server": {
      "command": "npx",
      "args": ["-y", "notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "YOUR_KEY",
        "NOTION_PAGE_ID": "YOUR_PAGE_ID"
      }
    }
  }
}

2. 将 YOUR_KEY 和 YOUR_PAGE_ID 替换为您的实际 Notion API 密钥和页面 ID
3. 重新启动 Claude 桌面以应用更改

🌟 功能

• 📝 Notion 集成 - 与 Notion 数据库、页面和块进行交互
• 🔌 通用 MCP 兼容性 - 适用于所有 MCP 客户端，包括 Cursor、Claude 桌面、Cline 和 Zed
• 🔍 数据检索 - 从 Notion 页面、块和数据库中获取信息
• ✏️ 内容创建 - 创建和更新 Notion 页面和块
• 📊 块管理 - 在 Notion 页面中追加、更新和删除块
• 💾 数据库操作 - 创建、查询和更新数据库
• 🔄 批量操作 - 在单个请求中执行多个操作
• 🗑️ 归档与恢复 - 归档和恢复 Notion 页面
• 🔎 搜索功能 - 按标题搜索 Notion 页面和数据库
• 💬 评论管理 - 获取、创建和回复页面和讨论中的评论
• 👥 用户管理 - 检索工作区用户和用户信息

📚 文档

可用工具

服务器提供以下整合工具，用于与 Notion 进行交互：

notion_pages

用于页面操作的综合工具，包括：

• 创建包含指定内容的新页面
• 更新页面属性
• 归档页面（移动到回收站）
• 恢复之前归档的页面
• 按标题搜索页面

示例操作：

{
  "payload": {
    "action": "create_page", // 其中之一："create_page", "archive_page", "restore_page", "search_pages", "update_page_properties"
    "params": {
      // 所选操作的具体参数
    }
  }
}

notion_blocks

用于块操作的完整工具包，包括：

• 检索块内容
• 获取子块
• 在父块中追加新块
• 更新现有块
• 删除块
• 执行批量操作（追加、更新、删除、混合）

示例操作：

{
  "payload": {
    "action": "append_block_children", // 其中之一："append_block_children", "retrieve_block", "retrieve_block_children", "update_block", "delete_block", "batch_append_block_children", "batch_update_blocks", "batch_delete_blocks", "batch_mixed_operations"
    "params": {
      // 所选操作的具体参数
    }
  }
}

notion_database

用于数据库交互的强大工具，包括：

• 创建具有自定义属性的新数据库
• 使用过滤器和排序查询数据库
• 更新数据库结构和属性

示例操作：

{
  "payload": {
    "action": "create_database", // 其中之一："create_database", "query_database", "update_database"
    "params": {
      // 所选操作的具体参数
    }
  }
}

notion_comments

用于管理 Notion 内容评论的工具：

• 从页面和块中获取评论
• 在页面中添加新评论
• 回复现有讨论

示例操作：

{
  "payload": {
    "action": "get_comments", // 其中之一："get_comments", "add_page_comment", "add_discussion_comment"
    "params": {
      // 所选操作的具体参数
    }
  }
}

notion_users

用于访问用户信息的工具：

• 列出所有工作区用户
• 获取特定用户的详细信息
• 检索当前机器人用户的信息

示例操作：

{
  "payload": {
    "action": "list_users", // 其中之一："list_users", "get_user", "get_bot_user"
    "params": {
      // 所选操作的具体参数
    }
  }
}

可用资源

服务器当前不暴露任何资源，而是专注于基于工具的操作。

🛠 开发

1. 克隆仓库

   git clone https://github.com/awkoy/notion-mcp-server.git
   cd notion-mcp-server
   

2. 安装依赖

   npm install
   

3. 设置环境变量

   • 创建一个 .env 文件，内容如下：

     NOTION_TOKEN=your_notion_api_key
     NOTION_PAGE_ID=your_notion_page_id
     

4. 构建项目

   npm run build
   

5. 运行检查器

   npm run inspector
   

🔧 技术细节

• 使用 TypeScript 和 MCP SDK（版本 1.7.0+）构建
• 使用官方 Notion API 客户端（@notionhq/client v2.3.0+）
• 遵循模型上下文协议规范
• 实现对 Notion 页面、块和数据库的 CRUD 操作
• 支持高效的批量操作以优化性能
• 使用 Zod 模式验证输入/输出

❓ 故障排除

• 常见问题

  • 认证错误：确保您的 Notion 令牌具有正确的权限，并且集成已为您的页面/数据库启用
  • 页面访问问题：确保您的集成已添加到您尝试访问的页面
  • 速率限制：Notion API 有速率限制 - 使用批量操作以优化请求

• 获取帮助

  • 在 GitHub 仓库 上创建问题
  • 查看 Notion API 文档
  • 访问 MCP 社区频道以获取帮助

🤝 贡献

欢迎贡献！请随时提交拉取请求。

1. 分叉仓库
2. 创建您的功能分支（git checkout -b feature/amazing-feature）
3. 提交您的更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开拉取请求

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。