Notion API MCP

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

MCP 概览

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

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

完整功能列表 →

快速开始

# Clone and setup
git clone https://github.com/yourusername/notion-api-mcp.git
cd notion-api-mcp
uv venv && source .venv/bin/activate

# Install and configure
uv pip install -e .
cp .env.integration.template .env

# Add your Notion credentials to .env:
# NOTION_API_KEY=ntn_your_integration_token_here
# NOTION_PARENT_PAGE_ID=your_page_id_here  # For new databases
# NOTION_DATABASE_ID=your_database_id_here  # For existing databases

# Run the server
python -m notion_api_mcp

入门指南

1. 创建 Notion 集成

1. 访问 https://www.notion.so/my-integrations
2. 点击“新建集成”
3. 为你的集成命名（例如，“我的 MCP 集成”）
4. 选择你将使用该集成的工作区
5. 复制“内部集成令牌” - 这将是你的 NOTION_API_KEY
   • 应以 "ntn_" 开头

2. 设置 Notion 访问

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

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

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

选项 B：现有数据库

1. 打开你的现有 Notion 数据库
2. 确保它已连接到你的集成（••• 菜单 > 添加连接）
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  # On Windows: .venv\Scripts\activate

1. 安装依赖项：

uv pip install -e .

1. 配置环境：

cp .env.integration.template .env

1. 使用你的 Notion 凭证编辑 .env 文件：

NOTION_API_KEY=ntn_your_integration_token_here

# Choose one or both of these depending on your needs:
NOTION_PARENT_PAGE_ID=your_page_id_here  # For creating new databases
NOTION_DATABASE_ID=your_database_id_here  # For working with existing databases

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",
        
        // Choose one or both:
        "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. 测试增强

   • 性能基准测试
   • 负载测试
   • 更多边缘情况
   • 扩展集成测试