notion-mcp

Overview Schema Source Related Servers Discussions Admin

notion_upload_file

Upload local, shared, Drive, or base64 files to Notion and attach them as new blocks on a page or block, with caption, position, and HTML embed options.

Instructions

Upload a file to Notion and attach it as a new block.

source accepts one of: • local:<relative-path> — a file under the notion-mcp private store (FILES_DIR). List with notion_list_local_files. • shared:<filename> — a file on the shared cross-MCP mount, written there by google-accounts-mcp download_attachment with destination='shared'. List with notion_list_local_files(location='shared'). • drive:<name-or-id> — a file in the shared Drive folder (DRIVE_FOLDER_NAME) Google Drive folder (read from google-accounts-mcp's credentials, read-only). • base64:<bytes> — raw base64 content; requires filename. Subject to MCP parameter size limits — prefer shared: or drive: for anything over ~20KB.

parent_page_id is a Notion page ID (find via notion_search_pages) OR any block ID that supports children (toggle, column, callout, ...) to attach the file inside that block.

position controls where the new block lands among the parent's children: 'end' (default), 'start', or a block ID to insert directly AFTER that block (get block IDs from notion_read_page(include_block_ids=True) or notion_list_files_on_page).

filename overrides the source filename when provided. caption is shown below the file block in Notion. Files larger than 20 MB are uploaded via Notion's multi-part protocol automatically. To swap the file in an existing block without moving it, use notion_replace_file instead.

embed_html=True attaches an .html/.htm file as an embed block that Notion renders in the page, instead of a downloadable file block (caption is not applied to embeds).

Cross-MCP file transfer

To upload a Gmail attachment to a Notion page:

google-accounts-mcp download_attachment(..., destination='shared')
notion_upload_file(source='shared:', parent_page_id=...) Files never traverse MCP parameters — no size limits.

Input Schema

Name	Required	Default
`source`	Yes
`caption`	No
`filename`	No
`position`	No	end
`embed_html`	No
`parent_page_id`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.2.2Oct 26, 2026

addedInput schema / properties / embed_html

Added value: +{
+  "default": false,
+  "title": "Embed Html",
+  "type": "boolean"
+}

First observedv0.1.0Aug 5, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations present, the description carries the full burden and does so: it discloses the 20 MB multi-part threshold, base64 payload size limits against MCP parameter caps, that Drive is read through google-accounts-mcp credentials read-only, and that caption is dropped for embeds. It also explains the side effect (a new block is appended to the parent's children) and where it lands.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then broken into a bulleted source list, prose for the remaining parameters, and a headed cross-MCP section, so scanning is easy. It is on the long side and the duplicated Drive folder phrasing ('DRIVE_FOLDER_NAME') plus the redundant google-accounts-mcp mentions are minor waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter upload tool, everything needed to call it correctly is present: value formats, anchor semantics, size thresholds, and the embed special case. An output schema exists, so the description is not obliged to describe return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must do all the work, and it defines every one of the six parameters. `source` gets four prefixed formats with constraints, `parent_page_id` broadens to any container block, `position` accepts 'end'/'start'/a block ID with the anchor semantics spelled out, and filename/caption/embed_html each get their override or rendering behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first line states a specific verb and resource ('Upload a file to Notion') plus the outcome ('attach it as a new block'), which distinguishes it from page-content tools. The closing line explicitly routes the in-place variant to notion_replace_file, so an agent can separate the two without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It enumerates all four source forms with the exact helper (notion_list_local_files, location='shared') that surfaces valid values, and points to notion_search_pages for parent_page_id. It names the exclusion case ('to swap the file in an existing block without moving it, use notion_replace_file') and gives a step-by-step cross-MCP recipe.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server