notion-full-mcp

notion-full-mcp

Notion MCP server with deep page reading, surgical block editing, safe snapshot/restore, file uploads (Notion-hosted images and PDFs), table row manipulation, page move and copy, and page restore from trash.

What's new in v0.5.1

• Tool annotations. Every tool declares whether it is read-only, additive or destructive, so MCP clients can decide what to run without asking.
• MCP Registry. The server is published to the official MCP Registry as io.github.cphoskins/notion-full-mcp.

What's new in v0.5.0

• Restore keeps the page in order. Subpages, inline databases and Notion-hosted files that are still on the page stay untouched, and the restored content is written around them in snapshot order.
• Restore brings items back from trash. A subpage, database or hosted file deleted after the snapshot is restored from Notion's trash with its ID, comments and history intact.
• Snapshots can carry files. snapshot_page with include_files downloads Notion-hosted images and files beside the JSON, and restore uploads them again in place.
• Fix: inserting more than 100 blocks after a block now keeps them in order.

What's new in v0.4.0

• Restore can no longer lose content. restore_page_from_snapshot writes the snapshot first and removes the old blocks only after that succeeds. A failed restore rolls back and leaves the page as it was. Subpages, inline databases and Notion-hosted files are never deleted.
• move_page works. It uses Notion's move endpoint, so the page keeps its ID, content, comments and subpages.
• copy_page_to_parent reports what it could not copy. Uncopyable block types are listed in skipped, and the original is archived only when everything was copied.
• Large and deep content. Lists nested more than two levels, tables over 100 rows and text over 2,000 characters are split across requests automatically.
• Mentions and equations survive edits. Find/replace, restore and copy keep user, page, database and date mentions and inline equations.
• Better errors and rate-limit handling. Errors carry Notion's own code and message. Rate-limited requests are retried using Retry-After.
• Database rows have titles. Search, page info and create return the title whatever the title column is called.
• More block types. Equation, bookmark, embed and externally hosted media blocks round-trip through snapshot/restore and copy.
• Optional file boundary. Set NOTION_MCP_FILE_ROOT to confine uploads, downloads and snapshots to one directory.

What's new in v0.3.0

• Page restore from trash. restore_page explicitly unarchives a page by sending archived=False. This is the counterpart to delete_block on a page and works around the intentional safety guard in update_page that blocks archived=False. Cascaded child archives are restored automatically when the parent is restored.
• Destructive page copy across parents. copy_page_to_parent is the workaround for Notion's public API not supporting parent changes. Recreates the page at the target parent with the same title, icon, and content, then archives the original. Handles paragraphs, headings, lists, tables, dividers, code blocks, and image/file blocks. Refuses to run if the source has nested child_page descendants (copy those manually).
• move_page stopped pretending. Notion's PATCH /pages/{id} endpoint silently ignores parent changes, so the tool returned an error instead. (v0.4.0 implements a real move.)

What's new in v0.2.0

• Notion file uploads. Upload images and files directly to Notion's own workspace storage instead of relying on an external image host. Works for PNG, JPEG, SVG, GIF, PDF, and any other Notion-supported attachment type.
• Image block helpers. upload_image_as_block uploads a file and inserts it at a position in one call. replace_image_block swaps an existing image's content while preserving its position in the parent. download_image_block pulls any image block's file to disk.
• Table row manipulation. insert_table_row adds a row to an existing table with automatic width validation. update_table_cell replaces the text of a single cell. No more rebuild-the-whole-table for small edits.

Install

pip install notion-full-mcp
# or
uv pip install notion-full-mcp

Quick Start

export NOTION_API_TOKEN="your-token-here"
notion-mcp

Claude Code Integration

Add to ~/.claude.json under mcpServers:

{
  "notion-full": {
    "type": "stdio",
    "command": "uvx",
    "args": ["notion-full-mcp"],
    "env": {
      "NOTION_API_TOKEN": "your-token-here"
    }
  }
}

Or for local development:

{
  "notion-full": {
    "type": "stdio",
    "command": "uv",
    "args": ["run", "--directory", "/path/to/notion-full-mcp", "notion-mcp"],
    "env": {
      "NOTION_API_TOKEN": "your-token-here"
    }
  }
}

Tools (33)

Search & Pages

Tool	Description
search_pages	Search pages by title
search	Search pages and/or databases
get_page_info	Get page metadata (title, parent, dates, URL)
create_page	Create a new page under a parent page or database
update_page	Update a page's title, icon, or archive status
move_page	Move a page under a new parent page, keeping its ID and content
restore_page	Restore a page (and its cascade-archived children) from trash
copy_page_to_parent	Recreate a page under a new parent page or database. Archives the original only when every block was copied

Reading

Tool	Description
read_page_deep	Read page with all nested children (recursive)
list_block_children	List direct children of a block or page
get_block	Get a single block by ID

Editing

Tool	Description
update_block_text	Replace all text in a block
find_replace_in_block	Find/replace text preserving formatting
update_block_rich_text	Update with full rich text specification

Inserting

Tool	Description
insert_text_after	Insert a text block after a specific block (paragraph, heading_1/2/3, bulleted_list_item, numbered_list_item, quote, callout, toggle, to_do, code, divider)
insert_blocks_after	Insert multiple blocks after a specific block
append_blocks_to_page	Append blocks to the end of a page

Deleting

Tool	Description
delete_block	Delete a block by ID

Comments

Tool	Description
create_comment	Add a comment to a page
list_comments	List all comments on a page or block

Databases

Tool	Description
get_database	Get database metadata and schema
query_database	Query a database with filters and sorts

Users

Tool	Description
get_self	Get the current authenticated user/bot
list_users	List all workspace users

Snapshot / Restore

Tool	Description
snapshot_page	Save complete page structure as JSON. include_files also saves Notion-hosted images and files
restore_page_from_snapshot	Restore page content from a snapshot. Writes first, rolls back on failure, keeps subpages and databases in place, restores deleted ones from trash and re-uploads saved files

Media & Files

Tool	Description
upload_file	Upload a file to Notion's own workspace storage (returns file_upload_id)
upload_image_as_block	Upload an image and insert it as a new image block in one step (after a block or appended to a page)
replace_image_block	Replace an existing image block with a newly uploaded file, preserving its position
download_image_block	Download the image file from an image block to disk — works for external URLs, Notion-hosted files, and file_upload references
upload_file_as_block	Upload any file (PDF, attachment) and insert it as a file block

Tables

Tool	Description
insert_table_row	Insert a new row into an existing table with automatic width validation
update_table_cell	Replace the text of a single cell in a table row

Tool annotations

Every tool carries MCP annotations so a client can decide what is safe to run without asking:

• Read-only (11): search, page and block reads, comments list, database reads and user lookups.
• Adds without loss (13): inserts, appends, uploads, page and comment creation, move_page, restore_page, and the two tools that write local files (snapshot_page, download_image_block).
• Marked destructive (9): update_block_text, update_block_rich_text, find_replace_in_block, update_table_cell, replace_image_block, delete_block, update_page, copy_page_to_parent and restore_page_from_snapshot. They overwrite, delete or archive existing content.

Block support and limits

• Round-trip (snapshot/restore and copy): paragraph, headings (including toggleable), bulleted and numbered lists, to-do, quote, callout, toggle, code, divider, table, columns, table of contents, equation, bookmark, embed, and externally hosted image, file, video, PDF and audio blocks.
• Never recreated from scratch: subpages, inline databases and synced blocks. Copy reports them as skipped.
• Restore of those blocks, and of Notion-hosted files:
  • Still on the page: left untouched, with restored content written around them in snapshot order (preserved). One that was dragged out of snapshot order stays where it is (out_of_order).
  • File saved with the snapshot: uploaded again and recreated in place (uploaded). Files over 20 MB, or over the workspace upload limit, are not uploaded.
  • In Notion's trash: brought back as the same block (restored_from_trash). Notion returns it to the end of the page, so a block that is still on the page and came later in the snapshot ends up above it and is reported as out_of_order.
  • Gone from trash, with no saved file: cannot be restored (skipped).
  • Why out_of_order blocks are not moved (by design): the Notion API has no way to reposition a block. The only way to move a subpage or database is to trash it and restore it, which sends it to the end of the page and, if it failed midway, would leave it in trash. Restore never deletes something it cannot recreate, so it reports the block and leaves it for you to drag into place.
• Snapshots: record subpages and inline databases as blocks, without their own content. Notion-hosted files are saved only with include_files; otherwise the snapshot holds links that expire within the hour.
• Queries: query_database returns at most 500 rows and sets truncated when more matched.
• Find/replace: matches within one formatting run. A phrase that spans a bold or link boundary is reported as not found.
• API version: requests use Notion API version 2022-06-28.

Configuration

Variable	Required	Purpose
NOTION_API_TOKEN	Yes	Integration secret
NOTION_MCP_FILE_ROOT	No	When set, uploads, downloads and snapshot files must be inside this directory

Development

uv run pytest --cov=notion_mcp      # unit tests, no credentials needed

A live check runs every tool against a real workspace. It works inside one scratch page under the parent you name and moves it to trash afterwards:

export NOTION_API_TOKEN="your-token-here"
export NOTION_TEST_PARENT_PAGE="page-id-shared-with-the-integration"
uv run python scripts/live_check.py

Notion API Token

1. Go to https://www.notion.so/my-integrations
2. Create a new integration
3. Copy the token (starts with ntn_)
4. Share the pages/databases you want to access with the integration

License

MIT