Notion Large File Upload

notion-large-file-upload-mcp

AI エージェント（Claude Desktop、Claude Code、Cursor、Zed）が、ローカルファイルを Notion にアップロードし、ページに添付できる MCP サーバーです。ファイルサイズは 最大 5 GB です。ファイルはパスを指定してディスクから読み取られるため、モデルのコンテキストを経由することはありません。

---

このサーバーが必要な理由

• Notion のホスト型 MCP サーバーは 20 MiB までです。 その notion-create-file-upload ツールは単一パートのアップロードしかできず、Notion のオープンソース MCP サーバーはアップロードを受け付けなくなりました。
• Base64 はコンテキストウィンドウを埋め尽くします。 大きなファイルを送信できる MCP サーバーもありますが、エージェントはファイルを Base64 として会話に渡さなければならず、数ファイルでモデルのコンテキストを使い切ってしまいます。
• エージェントは大きなファイルを諦めます。 アップロードする方法がなければ、エージェントは作成した画面録画、会議の音声、テストのスクリーンショット、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. 次のように設定します。
   • Name：notion-large-files
   • Type：command
   • Command：npx -y notion-large-file-upload-mcp
   • Environment Variables：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 では ;）です。この設定がない場合、アップロードツールは実行できません。

アップロード可能なファイルの制限

ツールはサーバーが実行されているマシンからファイルを読み取ります。制限がないと、プロンプトインジェクションに騙されたエージェントが ~/.ssh/id_rsa や .env などの機密ファイルを Notion にアップロードする可能性があります。そのため、NOTION_UPLOAD_ALLOWED_DIRS は必須です。エージェントが実際にファイルを生成するフォルダーを設定してください。

パスは絶対パスで指定する必要があります。また、確認の前にシンボリックリンクの参照先を解決するため、許可されたフォルダー内のリンクがその外を指すことはできません。許可されたフォルダー内にとどまるリンクの場合は、リンク名でアップロードされます。

アップロードの前に、サーバーは Notion がそのファイル形式に対応していることと、ファイルがワークスペースのアップロード上限（無料ワークスペースではファイルあたり 5 MiB）以内であることも確認します。そのため、マルチ 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 が含まれます。そのため、エージェントは再アップロードせずに attach_file_upload_to_notion で再試行できます。

---

attach_file_upload_to_notion

アップロード済みのファイルを Notion ページまたはブロックに添付します。Notion では、作成から 1 時間以内に添付されなかったアップロードは期限切れになります。

パラメーター	型	必須	説明
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 まで利用できます。
• アップロードは開始から 1 時間以内に添付する必要があるため、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