notion-full-mcp

Full-featured Notion MCP server with deep page reading, surgical block editing, snapshot/restore, file uploads (Notion-hosted images and PDFs), table row manipulation, page restore from trash, destructive page copy across parents, and all block types including tables.

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 deprecated and now raises. Notion's PATCH /pages/{id} endpoint silently ignores parent field changes -- calls return HTTP 200 but do nothing. The move_page tool now returns a clear error pointing callers to copy_page_to_parent or manual drag-and-drop in the Notion sidebar.

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 external hosts like imgur. 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	DEPRECATED -- Notion's public API does not support moving pages. Returns a clear error pointing to copy_page_to_parent
restore_page	Restore a page (and its cascade-archived children) from trash
copy_page_to_parent	Recreate a page under a new parent (destructive workaround for the missing move capability; archives the original by default)

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 (supports all block types: paragraph, heading_1/2/3, bulleted_list_item, numbered_list_item, quote, etc.)
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
restore_page_from_snapshot	Restore page from a snapshot (destructive)

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	Swap an existing image block's content 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

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