Notion API MCP

一个模型上下文协议 (MCP) 服务器，通过 Notion 的 API 提供高级的待办事项列表管理和内容组织功能。MCP 使 AI 模型能够与外部工具和服务交互，从而实现与 Notion 强大功能的无缝集成。

MCP 概述

基于 Python 的 MCP 服务器，使 AI 模型能够与 Notion 的 API 交互，提供：

• 待办事项管理：创建、更新和跟踪具有富文本、截止日期、优先级和嵌套子任务的任务
• 数据库操作：创建和管理具有自定义属性、过滤器和视图的 Notion 数据库
• 内容组织：使用 Markdown 支持、分层列表和块操作来构建和格式化内容
• 实时集成：通过清晰的异步实现与 Notion 的工作区、页面和数据库直接交互

完整功能列表 →

快速开始

# 克隆和设置
git clone https://github.com/yourusername/notion-api-mcp.git
cd notion-api-mcp
uv venv && source .venv/bin/activate

# 安装和配置
uv pip install -e .
cp .env.integration.template .env

# 将您的 Notion 凭据添加到 .env：
# NOTION_API_KEY=ntn_your_integration_token_here
# NOTION_PARENT_PAGE_ID=your_page_id_here  # 用于新数据库
# NOTION_DATABASE_ID=your_database_id_here  # 用于现有数据库

# 运行服务器
python -m notion_api_mcp

开始使用

1. 创建 Notion 集成

1. 转到 https://www.notion.so/my-integrations
2. 点击 "New integration"（新建集成）
3. 命名您的集成（例如，“My MCP Integration”）
4. 选择您将使用集成的 workspace（工作区）
5. 复制 "Internal Integration Token"（内部集成令牌） - 这将是您的 NOTION_API_KEY
   • 应该以 "ntn_" 开头

2. 设置 Notion 访问权限

您需要一个父页面（用于创建新数据库）或一个现有数据库 ID：

选项 A：用于新数据库的父页面

1. 在浏览器中打开 Notion
2. 创建一个新页面或打开一个您想要创建数据库的现有页面
3. 点击右上角的 ••• 菜单
4. 选择 "Add connections"（添加连接）并选择您的集成
5. 从 URL 复制页面 ID - 它是最后一个斜杠之后和问号之前的字符串
   • 示例：在 https://notion.so/myworkspace/123456abcdef... 中，ID 是 123456abcdef...
   • 这将是您的 NOTION_PARENT_PAGE_ID

选项 B：现有数据库

1. 打开您现有的 Notion 数据库
2. 确保它已连接到您的集成（••• 菜单 > Add connections（添加连接））
3. 从 URL 复制数据库 ID
   • 示例：在 https://notion.so/myworkspace/123456abcdef...?v=... 中，ID 是 123456abcdef...
   • 这将是您的 NOTION_DATABASE_ID

3. 安装 MCP 服务器

1. 创建虚拟环境：

cd notion-api-mcp
uv venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

2. 安装依赖项：

uv pip install -e .

3. 配置环境：

cp .env.integration.template .env

4. 使用您的 Notion 凭据编辑 .env：

NOTION_API_KEY=ntn_your_integration_token_here

# 根据您的需要选择其中一个或两个：
NOTION_PARENT_PAGE_ID=your_page_id_here  # 用于创建新数据库
NOTION_DATABASE_ID=your_database_id_here  # 用于处理现有数据库

4. 配置 Claude Desktop

重要提示：虽然服务器支持 .env 文件和环境变量，但 Claude Desktop 特别需要在其配置文件中进行配置才能使用 MCP。

添加到 Claude Desktop 的配置 (~/Library/Application Support/Claude/claude_desktop_config.json)：

{
  "mcpServers": {
    "notion-api": {
      "command": "/path/to/your/.venv/bin/python",
      "args": ["-m", "notion_api_mcp"],
      "env": {
        "NOTION_API_KEY": "ntn_your_integration_token_here",
        
        // 选择其中一个或两个：
        "NOTION_PARENT_PAGE_ID": "your_page_id_here",
        "NOTION_DATABASE_ID": "your_database_id_here"
      }
    }
  }
}

注意：即使您配置了 .env 文件，您也必须将这些环境变量添加到 Claude Desktop 配置中，以便 Claude 使用 MCP。.env 文件主要用于本地开发和测试。

文档

• 配置详情 - 详细的配置选项和环境变量
• 功能 - 完整的功能列表和功能
• 架构 - 可用工具和使用示例的概述
• API 参考 - 详细的 API 端点和实现细节
• 测试覆盖率矩阵 - 测试覆盖率和验证状态
• 依赖项 - 项目依赖项和版本信息
• 更新日志 - 开发进度和更新

开发

该服务器在整个过程中使用现代 Python 异步功能：

• 使用 Pydantic 模型进行类型安全配置
• 使用 httpx 进行异步 HTTP 以获得更好的性能
• 清晰的 MCP 集成，用于公开 Notion 功能
• 正确的资源清理和错误处理

调试

该服务器包括全面的日志记录：

• 用于开发的控制台输出
• 作为服务运行时进行文件日志记录
• 详细的错误消息
• 调试级别的请求/响应日志记录

设置 PYTHONPATH 以在直接运行时包含项目根目录：

PYTHONPATH=/path/to/project python -m notion_api_mcp

未来发展

计划的增强功能：

1. 性能优化

   • 添加请求缓存
   • 优化数据库查询
   • 实施连接池

2. 高级功能

   • 多工作区支持
   • 批量操作
   • 实时更新
   • 高级搜索功能

3. 开发者体验

   • 交互式 API 文档
   • 用于常见操作的 CLI 工具
   • 其他代码示例
   • 性能监控

4. 测试增强

   • 性能基准
   • 负载测试
   • 其他边缘情况
   • 扩展的集成测试