Notion Large File Upload

notion-large-file-upload-mcp

一个 MCP 服务，可让 AI Agent（Claude Desktop、Claude Code、Cursor、Zed）将最大 5 GB 的本地文件上传到 Notion，并将其附加到页面。它按路径从磁盘读取每个文件，因此文件不会经过模型的上下文。

---

为什么需要此服务

• Notion 托管的 MCP 服务限制为 20 MiB。 它的 notion-create-file-upload 工具只支持单部分上传，而 Notion 的开源 MCP 服务已不再接受任何上传。
• Base64 会占满上下文窗口。 有些 MCP 服务可以发送更大的文件，但 Agent 必须通过对话以 Base64 格式传递文件，上传几个文件后就会耗尽模型的上下文。
• Agent 会放弃处理大文件。 如果无法上传这些文件，Agent 就会退而使用缩略图或链接，而不是上传它们生成的屏幕录制、会议音频、测试截图或 PDF 报告。

notion-large-file-upload-mcp 封装了 notion-multipart-uploader，提供以下功能：

• 以流方式分块，每块 10 MiB：不会将 5 GB 的文件加载到 RAM 中。
• 并发上传分块：通过工作队列并行执行分段上传。
• 弹性重试引擎：自动处理速率限制（429）、服务器过载（529）、带抖动的指数退避以及 Retry-After 标头。
• 直接附加块：可将已上传的资源附加到页面或块，作为 video、pdf、image、audio 或 file 块。
• 进度与取消：上传时发送 MCP 进度通知，并在客户端取消工具调用时停止上传。

---

快速设置

1. Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "notion-large-files": {
      "command": "npx",
      "args": ["-y", "notion-large-file-upload-mcp"],
      "env": {
        "NOTION_KEY": "secret_your_notion_integration_token",
        "NOTION_UPLOAD_ALLOWED_DIRS": "/Users/me/Videos/exports:/Users/me/Documents/reports"
      }
    }
  }
}

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

---

2. Cursor IDE

1. 打开 Cursor Settings -> Features -> MCP。
2. 点击 Add New MCP Server。
3. 配置：
   • 名称：notion-large-files
   • 类型：command
   • 命令：npx -y notion-large-file-upload-mcp
   • 环境变量：NOTION_KEY=secret_... 和 NOTION_UPLOAD_ALLOWED_DIRS=/path/to/exports

---

3. Claude Code / CLI

claude mcp add notion-large-files -e NOTION_KEY=secret_... -e NOTION_UPLOAD_ALLOWED_DIRS=/path/to/exports -- npx -y notion-large-file-upload-mcp

---

配置

环境变量	必需	说明
NOTION_KEY	是	Notion 集成令牌。也接受 NOTION_API_KEY 和 NOTION_TOKEN。
NOTION_UPLOAD_ALLOWED_DIRS	是	允许上传文件的目录，使用 : 分隔（Windows 上使用 ;）。未设置此变量时，上传工具将拒绝运行。

限制可上传的文件

工具会从运行该服务的计算机读取文件。如果不加限制，被提示词注入欺骗的 Agent 可能会将 ~/.ssh/id_rsa 或 .env 等敏感文件上传到 Notion。因此必须设置 NOTION_UPLOAD_ALLOWED_DIRS：将其设为 Agent 实际生成文件的文件夹。

路径必须是绝对路径，并且会在检查前解析符号链接，因此允许的文件夹中的链接无法指向该文件夹之外。指向允许文件夹内位置的链接会以链接名称上传。

上传前，服务还会检查 Notion 是否支持该文件类型，以及文件是否符合工作区的上传限制（免费工作区每个文件为 5 MiB），让 Agent 收到清晰的错误提示，而不是在多 GB 文件上传失败后才发现问题。

---

可用工具

upload_large_file_to_notion

将任意大小（最高 5 GB）的本地文件上传到 Notion，并返回 Notion 的 file_upload ID。

参数	类型	必填	描述
filePath	string	是	磁盘上本地文件的绝对路径
mimeType	string	否	MIME 类型（例如，video/mp4）。若省略，则自动推断

---

upload_and_attach_to_notion

上传本地文件，并立即在目标 Notion 页面或区块中创建子区块。

参数	类型	必填	描述
filePath	string	是	磁盘上本地文件的绝对路径
blockId	string	是	目标 Notion 页面 ID 或父区块 ID
blockType	string	否	video、pdf、image、audio 或 file（若省略，则根据 MIME 类型推断）
mimeType	string	否	MIME 类型（若省略，则自动推断）
caption	string	否	可选的说明文字，显示在区块下方（最多 2,000 个字符）

如果上传成功但附加失败（例如，页面未与集成共享），错误中会包含文件 ID，以便 Agent 使用 attach_file_upload_to_notion 重试，而无需再次上传。

---

attach_file_upload_to_notion

将已上传的文件附加到 Notion 页面或区块。Notion 会在上传创建一小时后，使尚未附加的上传失效。

参数	类型	必填	描述
fileUploadId	string	是	上传工具返回的 file_upload ID
blockId	string	是	目标 Notion 页面 ID 或父区块 ID
blockType	string	是	video、pdf、image、audio 或 file
caption	string	否	可选的说明文字，显示在区块下方（最多 2,000 个字符）

---

限制

• 服务会从运行它的计算机读取文件，因此需要使用可运行本地服务的 MCP 客户端。在 claude.ai 或 ChatGPT 聊天中附加的文件不在该磁盘上。
• 免费版 Notion 工作区接受最大 5 MiB 的文件。付费计划允许上传最高 5 GB 的文件。
• 每次上传都必须在开始后一小时内附加，因此上传 5 GB 文件需要约 12 Mbit/s 的上传带宽。

它在 MCP Registry 中的名称是 io.github.shoubhiksaha/notion-large-file-upload。

---

本地开发

git clone https://github.com/shoubhiksaha/notion-multipart-uploader.git
cd notion-multipart-uploader
npm install          # one install for the library and the server (npm workspace)
npm run test:mcp     # builds the library and runs the server's tests against it
NOTION_KEY="secret_..." NOTION_UPLOAD_ALLOWED_DIRS="$PWD" npm start -w mcp-server

此服务器在当前检出目录中链接到该库，因此构建库后即可使用更改。测试会使用模拟的 Notion API，通过 stdio 启动服务器，因此不需要令牌或网络访问。有关发布流程，请参阅 CONTRIBUTING.md。

许可证

MIT © Shoubhik Saha