Easy Notion MCP
Easy Notion MCP
Markdown-first MCP server that connects AI agents to Notion. Agents write markdown — easy-notion-mcp converts it to Notion's block API and back again.
28 tools · 24 block types · 92% fewer tokens vs official Notion MCP · Full round-trip fidelity
npx easy-notion-mcpSee it in action → Live Notion page created and managed entirely through easy-notion-mcp.

Contents: Comparison · Setup · Config · Why markdown · How it works · Tools · Block types · Round-trip · Databases · Security · FAQ · Community
How does easy-notion-mcp compare to other Notion MCP servers?
Feature | easy-notion-mcp | Official Notion MCP (npm) | better-notion-mcp |
Content format | ✅ Standard GFM markdown | ❌ Raw Notion API JSON | ⚠️ Markdown (limited block types) |
Block types | ✅ 24 (toggles, columns, callouts, equations, embeds, tables, file uploads, task lists) | ⚠️ All (as raw JSON) | ⚠️ ~7 (headings, paragraphs, lists, code, quotes, dividers) |
Round-trip fidelity | ✅ Full — read markdown, modify, write back | ❌ Raw JSON requires block reconstruction | ⚠️ Unsupported blocks silently dropped |
Tools | 28 individually-named tools | 18 auto-generated from OpenAPI | 9 composite tools (39 actions) |
File uploads | ✅ | ✅ 5-step lifecycle | |
Prompt injection defense | ✅ Content notice prefix + URL sanitization | ❌ | ❌ |
Database entry format | Simple | Simplified key-value pairs | Simplified key-value pairs |
Auth options | API token or OAuth | API token or OAuth | API token or OAuth |
How many tokens does easy-notion-mcp save?
Operation | easy-notion-mcp | better-notion-mcp | Official Notion MCP | Savings vs Official |
Page read | 291 tokens | ⚠️ 236 tokens | 6,536 tokens | 95.5% |
DB query (5 rows) | 347 tokens | 704 tokens | 2,983 tokens | 88.4% |
Search (3 results) | 298 tokens | 347 tokens | 1,824 tokens | 83.7% |
Total (weighted) | 936 tokens | 1,287 tokens | 11,343 tokens | 91.7% |
⚠️ better-notion-mcp page reads appear smaller because they silently drop 11 block types (callouts, toggles, tables, task lists, equations, bookmarks, embeds). On equal content coverage, easy-notion-mcp is more efficient.
Measured by running all three MCP servers against the same Notion content and counting tokens with tiktoken cl100k_base. Raw responses saved for verification.
Related MCP server: MCP Notion Server (@suncreation)
How do I set up easy-notion-mcp?
With API token
Create a Notion integration, copy the token, share your pages with it.
Claude Code:
claude mcp add notion -s user \
-e NOTION_TOKEN=ntn_your_integration_token \
-- npx -y easy-notion-mcpThis registers the server in your Claude Code user-level config (-s user) and passes NOTION_TOKEN directly to the MCP child process via -e. Your shell environment and rcfiles are untouched — the token lives in Claude Code's config file, scoped to this server, and is not visible to other processes. To set a default parent page for create_page, add -e NOTION_ROOT_PAGE_ID=<page-id> to the same command.
OpenClaw:
openclaw config set mcpServers.notion.command "npx"
openclaw config set mcpServers.notion.args '["-y","easy-notion-mcp"]'Then provide the token via the parent shell environment before starting OpenClaw:
export NOTION_TOKEN=ntn_your_integration_tokenThis export form is the generic fallback for any MCP client that inherits the parent shell environment. Caveat: it only persists for the current shell session unless you add it to your shell rcfile, which has its own security implications — prefer the -e form above when using Claude Code specifically.
Claude Desktop / Cursor / Windsurf — add to your MCP config file:
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "easy-notion-mcp"],
"env": {
"NOTION_TOKEN": "ntn_your_integration_token"
}
}
}
}Config file locations: Claude Desktop → claude_desktop_config.json · Cursor → .cursor/mcp.json · Windsurf → ~/.windsurf/mcp.json
{
"servers": {
"notion": {
"command": "npx",
"args": ["-y", "easy-notion-mcp"],
"env": {
"NOTION_TOKEN": "ntn_your_integration_token"
}
}
}
}With OAuth
API-token + stdio is the lower-friction default. If you're running a shared deployment or want per-user access, OAuth handles authentication with no token to copy-paste.
Start the server:
npx easy-notion-mcp-httpRequires NOTION_OAUTH_CLIENT_ID and NOTION_OAUTH_CLIENT_SECRET env vars. See OAuth setup below.
Claude Code:
claude mcp add notion --transport http http://localhost:3333/mcpOpenClaw:
openclaw config set mcpServers.notion.transport "http"
openclaw config set mcpServers.notion.url "http://localhost:3333/mcp"Claude Desktop:
Go to Settings → Connectors → Add custom connector, enter http://localhost:3333/mcp.
Your browser will open to Notion's authorization page. Pick the pages to share, click Allow, done.
If you want to register easy-notion-mcp per-project instead of user-wide, paste the following into a .mcp.json file at your project's root:
{
"mcpServers": {
"easy-notion-mcp": {
"command": "npx",
"args": ["-y", "easy-notion-mcp"],
"env": {
"NOTION_TOKEN": "ntn_your_integration_token",
"NOTION_ROOT_PAGE_ID": "your_root_page_id"
}
}
}
}Replace the placeholder values with your real Notion integration token and (optional) root page ID. Note that this file should live in your project, not in this repo — Claude Code will auto-register any server it finds in a project-scoped .mcp.json and try to start it, so committing one with placeholder credentials will cause "Failed to connect" on repo open.
Dify / n8n / FlowiseAI (Docker-based platforms):
Run the HTTP server on your host machine:
export NOTION_MCP_BEARER=$(openssl rand -hex 32)
NOTION_TOKEN=ntn_your_integration_token \
NOTION_MCP_BIND_HOST=0.0.0.0 \
NOTION_MCP_BEARER=$NOTION_MCP_BEARER \
npx easy-notion-mcp-httpIn your platform's MCP server settings, use host.docker.internal instead of localhost, and add the bearer to the request headers:
http://host.docker.internal:3333/mcp
Authorization: Bearer <your NOTION_MCP_BEARER value>Why not localhost? These platforms typically run in Docker.
localhostinside a container refers to the container itself, not your host machine.host.docker.internalbridges the gap.HTTP host and bearer: The HTTP server binds
127.0.0.1by default and static-token mode requiresNOTION_MCP_BEARER.host.docker.internalreaches the host's bridge IP, so setNOTION_MCP_BIND_HOST=0.0.0.0on the host and send the bearer header on every client request. OAuth mode, which issues per-user bearers, is the alternative for shared Docker deployments.
easy-notion-mcp works with any MCP-compatible client. The server runs via stdio (API token mode) or HTTP (OAuth or API token mode).
If you run into questions during setup, the Discord community is a good place to ask. The #easy-notion-mcp channel covers setup and design discussion. Bugs go on GitHub issues.
Configuration
Stdio mode (API token)
Variable | Required | Default | Description |
| Yes | — | Notion API integration token |
| No | — | Default parent page ID |
| No |
| Skip content notice on |
About
.envfiles (contributors only): easy-notion-mcp loads a.envfile from the current working directory viadotenv. In practice this means.envonly "just works" when you run the server from a cloned repo checkout (node dist/index.jsafternpm install && npm run build), because the repo root is your cwd. It is not loaded when the package is invoked vianpx easy-notion-mcpor a global install from an arbitrary directory — that is standard npm CLI behavior. For thenpxpath, passNOTION_TOKENvia the-eflag in the Claude Code setup above, or via your MCP client's configenvblock.
OAuth / HTTP transport
Run npx easy-notion-mcp-http to start the HTTP server with OAuth support.
Variable | Required | Default | Description |
| Yes (OAuth mode) | — | Notion public integration OAuth client ID |
| Yes (OAuth mode) | — | Notion public integration OAuth client secret |
| No |
| HTTP server port |
| No |
| OAuth callback URL |
| No |
| Bind address. Default is loopback; set |
| Yes (static-token mode) | — | Shared-secret bearer required by clients in static-token HTTP mode. Server refuses to start without it. Not required in OAuth mode. |
To get OAuth credentials, create a public integration at notion.so/profile/integrations and configure http://localhost:3333/callback as the redirect URI.
In OAuth mode, create_page works without NOTION_ROOT_PAGE_ID — pages are created in the user's private workspace section by default.
HTTP mode security posture
The HTTP transport is designed for trusted networks: single-operator self-hosting with a bearer secret, or OAuth for shared deployments. It is not hardened for direct exposure to the open internet; put a reverse proxy with TLS in front of it if you need remote access.
Static-token mode requires a bearer. Starting npx easy-notion-mcp-http with only NOTION_TOKEN set will refuse to start. Set a shared-secret bearer in the server's environment, then configure your MCP client to send it as Authorization: Bearer <secret> on every /mcp request:
export NOTION_MCP_BEARER=$(openssl rand -hex 32)
NOTION_TOKEN=ntn_your_integration_token npx easy-notion-mcp-httpThe bearer is compared with crypto.timingSafeEqual. Missing or wrong bearers get 401 { "error": "invalid_token" }. Rotate the secret by restarting the server with a new value.
Default bind is loopback. The server binds 127.0.0.1 by default — local processes only. Set NOTION_MCP_BIND_HOST=0.0.0.0 to expose all interfaces, or a specific IP like 192.168.1.5 to expose one. Bearer is required regardless of bind.
Bearer-always is the trust boundary. DNS-rebinding protection is not wired on the /mcp endpoint, and CORS on the OAuth registration/token endpoints (/register, /token, /revoke) is permissive. Treat the bearer, or OAuth's per-user bearer, as the only thing standing between the network and your Notion workspace. Keep it set even for loopback-only deployments. If you need to expose this server beyond a trusted network, put it behind a reverse proxy that handles TLS and origin checks.
OAuth mode for multi-user / remote. OAuth has its own per-user bearer enforcement; NOTION_MCP_BEARER is not required in OAuth mode. For shared deployments, OAuth's per-user identity model is the right shape — static-token + bearer is intended for single-operator self-hosting.
file:// uploads are stdio-only. Markdown passed to create_page, append_content, replace_content, update_section, or update_page.cover with file:// URLs is rejected over HTTP. Use stdio mode for local-file workflows (create_page_from_file is also stdio-only), or host the file at an HTTPS URL and use that URL in the markdown.

Why markdown-first?
The official Notion MCP npm package returns raw API JSON — deeply nested block objects with ~120 tokens of metadata per block. Other servers convert to markdown but support only a handful of block types, silently dropping callouts, toggles, tables, equations, and more.
easy-notion-mcp uses standard GFM markdown that agents already know. There's nothing new to learn, no custom tag syntax, no block objects to construct. The agent writes markdown, easy-notion-mcp handles the conversion to Notion's block API — and back again, with 24 block types preserved.
This means agents can edit existing content. Read a page, get markdown back, modify the string, write it back. Nothing is lost. Agents edit Notion pages the same way they edit code — as text.
How does easy-notion-mcp work?
Pages — write and read markdown:
create_page({
title: "Sprint Review",
markdown: "## Decisions\n\n- Ship v2 by Friday\n- [ ] Update deploy scripts\n\n> [!WARNING]\n> Deploy window is Saturday 2–4am only"
})Read it back — same markdown comes out:
read_page({ page_id: "..." }){ "markdown": "## Decisions\n\n- Ship v2 by Friday\n- [ ] Update deploy scripts\n\n> [!WARNING]\n> Deploy window is Saturday 2–4am only" }Modify the string, call replace_content, done. Or target a single section by heading name with update_section. Or do a surgical find_replace without touching the rest of the page. Pages can also have emoji icons and cover images set via create_page or update_page.
Databases — write simple key-value pairs:
add_database_entry({
database_id: "...",
properties: { "Status": "Done", "Priority": "High", "Due": "2026-05-15", "Tags": ["v2", "launch"] }
})No property type objects, no nested { select: { name: "Done" } } wrappers. easy-notion-mcp fetches the database schema at runtime and converts automatically. Agents pass { "Status": "Done" }, easy-notion-mcp does the rest.
Errors tell you how to fix them. A wrong heading name returns the available headings. A missing page suggests sharing it with the integration. A bad filter tells you to call get_database first. Agents can self-correct without asking the user for help.
Complex content works. Nested toggles inside toggles, columns with mixed content types (lists + code blocks + blockquotes), deep list nesting, and full unicode (Japanese, Chinese, Arabic, emoji) all round-trip cleanly. update_section heading search is case-insensitive and returns available headings on miss. add_database_entries handles partial failures — succeeded and failed entries are returned separately so agents can retry just the failures.

What tools does easy-notion-mcp provide?
easy-notion-mcp includes 29 individually-named tools across 5 categories. Each tool is self-documenting with complete usage examples — agents know exactly how to use every tool from the first message, with no extra round-trips needed.
Pages (13 tools)
Tool | Description |
| Create a page from markdown |
| Create a page from a local markdown file (stdio only) |
| Read a page as markdown |
| Append markdown to a page |
| Replace all page content atomically (preserves block IDs of matched blocks) |
| Update a section by heading name (destructive; duplicate_page first for irreplaceable content) |
| Find and replace text, preserving files |
| Update a single block by ID (preserves block identity for deep links and comments) |
| Update title, icon, or cover |
| Copy a page and its content |
| Move a page to trash |
| Move a page to a new parent |
| Restore an archived page |
Navigation (3 tools)
Tool | Description |
| List child pages under a parent |
| Search pages and databases |
| Get the shareable URL |
Databases (9 tools)
Tool | Description |
| Create a database with typed schema |
| Update database schema (add, rename, or remove properties; change title; trash or restore) |
| Get database schema, property names, and options |
| List all databases the integration can access |
| Query with filters, sorts, or text search |
| Add a row using simple key-value pairs |
| Add multiple rows in one call |
| Update a row using simple key-value pairs |
| Delete (archive) a database entry |
Database write tools reject unknown property names and unsupported property types with a clear error instead of silently dropping them. Call
get_databasefirst to confirm property names and types. Supported property types for writes:title,rich_text,number,select,multi_select,date,checkbox,url,phone,status,relation,people. Forpeople, pass a single user-ID string or an array of user IDs. Computed types (formula,rollup,unique_id,created_time,last_edited_time,created_by,last_edited_by) are populated by Notion and cannot be set via API. Value writes are also rejected forfiles,verification,place,location, andbutton. For relation writes, pass either a single page-ID string ("Projects": "page-id") or an array ("Projects": ["id-a", "id-b"]); an empty array clears the relation.
easy-notion-mcp fetches the database schema, maps values to Notion's property format, and handles type conversion automatically when agents pass simple key-value pairs like { "Status": "Done" }. Schema is cached for 5 minutes to avoid redundant API calls during batch operations.
Comments (2 tools)
Tool | Description |
| List comments on a page |
| Add a comment to a page |
Users (2 tools)
Tool | Description |
| List workspace users |
| Get the current bot user |
What block types does easy-notion-mcp support?
easy-notion-mcp supports 24 Notion block types using standard markdown syntax extended with conventions for Notion-specific blocks like toggles, columns, and callouts. Agents write familiar markdown — easy-notion-mcp handles the conversion to and from Notion's block format.
Standard markdown
Syntax | Markdown |
Headings |
|
Bold, italic, strikethrough |
|
Inline code |
|
Links |
|
Images |
|
Bullet list |
|
Numbered list |
|
Task list |
|
Blockquote |
|
Code block |
|
Table | Standard pipe table syntax |
Divider |
|
Notion-specific syntax
Block | Syntax |
Toggle |
|
Columns |
|
Callout (note) |
|
Callout (tip) |
|
Callout (warning) |
|
Callout (important) |
|
Callout (info) |
|
Callout (success) |
|
Callout (error) |
|
Equation |
|
Table of contents |
|
Embed |
|
Bookmark | Bare URL on its own line |
File upload (image) |
|
File upload (file) |
|
Can I read and rewrite pages without losing formatting?
Yes. Round-trip fidelity is a core design guarantee of easy-notion-mcp, not a side effect.
What you write is what you read back. read_page returns the exact same markdown syntax that create_page accepts — headings, lists, tables, callouts, toggles, columns, equations, all of it.
When a page contains Notion block types this server does not yet represent, such as synced_block, child_database, child_page, or link_to_page, read_page includes a warnings field with the omitted block IDs and types. Round-tripping that markdown through replace_content would delete those blocks, so the warning lets agents avoid unsafe rewrites.
easy-notion-mcp enables agents to read a page, modify the markdown string, and write it back without losing formatting, structure, or content. No format translation. No block reconstruction. Agents edit Notion pages the same way they edit code — as text.
What's the difference between find_replace and replace_content?
easy-notion-mcp provides three editing strategies for different use cases:
replace_content— Replaces all content on a page with new markdown. Best for full rewrites.update_section— Replaces a single section identified by heading name. Best for updating one part of a page.find_replace— Finds and replaces specific text anywhere on the page, preserving all other content and attached files. Best for surgical edits.
How does easy-notion-mcp handle databases?
easy-notion-mcp provides 9 database tools that abstract away Notion's complex property format. Agents pass simple key-value pairs like { "Status": "Done", "Priority": "High" }; easy-notion-mcp fetches the database schema at runtime, caches it for 5 minutes, and converts to Notion's property format automatically.
easy-notion-mcp supports creating and updating databases with typed schemas, querying with filters and sorts, and bulk operations via add_database_entries (multiple rows in one call).
What about security and prompt injection?
easy-notion-mcp includes two layers of security for production deployments:
Prompt injection defense: read_page responses include a content notice prefix instructing the agent to treat Notion data as content, not instructions. This prevents page content from hijacking agent behavior. Set NOTION_TRUST_CONTENT=true to disable this if you control the workspace.
URL sanitization: javascript:, data:, and other unsafe URL protocols are stripped and rendered as plain text. Only http:, https:, and mailto: are allowed.

Frequently Asked Questions
How is easy-notion-mcp different from the official Notion MCP server?
The official Notion MCP npm package (@notionhq/notion-mcp-server) is a raw API proxy — it returns unmodified Notion JSON, costing ~90% more tokens per operation. easy-notion-mcp converts everything to standard GFM markdown that agents already know, supports 24 block types with round-trip fidelity, and includes prompt injection defense. Notion also offers a separate hosted remote MCP server (OAuth-based) that uses a custom HTML-tag-based markdown format — easy-notion-mcp uses standard markdown syntax instead.
What MCP clients does easy-notion-mcp work with?
easy-notion-mcp works with any MCP-compatible client, including Claude Desktop, Claude Code, Cursor, VS Code Copilot, Windsurf, and OpenClaw. It supports both stdio transport (API token) and HTTP transport (OAuth). See the setup instructions for copy-pasteable configs for each client.
Does easy-notion-mcp support file uploads?
Yes. easy-notion-mcp supports file uploads using the file:/// protocol in markdown syntax. Upload images with  and files with [name](file:///path/to/file.pdf).
Does easy-notion-mcp handle nested and complex content?
Yes. Nested toggles inside toggles, columns with mixed content types (lists, blockquotes, and code blocks in different columns), nested bullet and numbered lists, and full unicode support including Japanese, Chinese, Russian, Arabic, and emoji — all round-tripping cleanly.
Does easy-notion-mcp handle partial failures in batch operations?
Yes. add_database_entries returns separate succeeded and failed arrays. If one entry fails validation, the others still get created. Agents can retry just the failures without re-sending the whole batch.
Community
There's a community Discord at discord.gg/S8cghJSVBU. The #easy-notion-mcp channel covers setup questions and design discussion, and the rest of the server is open for show-and-tell or general conversation. For bugs and concrete feature requests, GitHub issues remain the canonical channel.
Contributing
Issues and PRs welcome on GitHub.
License
MIT
Available Tools
43 toolsadd_commentA
Add a comment to a page. Supports inline markdown and page mentions with @Title. Unlike append_content, a mention the integration cannot resolve is not downgraded to a plain link and returns no warning, so the call can fail. Returns { id, content }.
Inputs: text (required), page_id (required), collapse_soft_wraps.
add_database_entriesA
Create multiple entries in a database in one call. Each entry uses the same simple key-value format as add_database_entry. Returns per-entry results — partial failures don't block the batch.
Inputs: entries (required), page_id, database_id.
add_database_entryA
Create one database entry using simple key-value property inputs. Call get_database first to see available property names and valid select/status options.
Writable property values use simple inputs:
title, rich_text: string
number: number
select, status: option name string
multi_select: array of option name strings
date: ISO date string (start only)
checkbox: boolean
url, email, phone: string
relation: string or array of page IDs
people: string or array of user IDs
Not writable from this tool:
formula, rollup, unique_id, created_time, last_edited_time, created_by, last_edited_by: computed by Notion
files, verification, place, location, button: not supported for value writes here
Example: { "Name": "Buy groceries", "Status": "Todo", "Priority": "High", "Due": "2025-03-20", "Tags": ["Personal"] }.
Inputs: properties (required), page_id, database_id.
append_contentA
Append markdown content to an existing page. The server converts markdown into native Notion blocks, not flat/plain text. The server automatically handles Notion API limits: batches more than 100 child blocks, splits rich text over 2000 characters, and writes deeply nested blocks in additional passes, so callers can append large documents in one call with no need to pre-chunk or pre-split. Supports the same syntax as create_page; read resource easy-notion://docs/markdown for the full syntax guide. Page mentions: @Title; a mention the integration cannot resolve is downgraded to a plain link and reported with a mention_target_unresolved warning. Returns: { success: true, blocks_added: }, plus block_map for top-level appended blocks when present and warnings when present.
Inputs: page_id (required), markdown (required), return_block_map, collapse_soft_wraps.
archive_pageC
Archive a page in Notion.
Inputs: page_id (required), dry_run.
archive_toggleA
Archive one toggle by title from a page. Searches recursively and matches plain toggle blocks plus toggleable heading_1, heading_2, and heading_3 blocks using case-insensitive trimmed text. Archives the matched container block; children are not deleted individually. Missing titles return the available toggle titles.
Inputs: title (required), page_id (required), dry_run.
create_databaseA
Create a database under a parent page.
Supported property types and extras:
title
rich_text (alias: text)
number (optional: format, for example "dollar", "percent", "number_with_commas")
select, multi_select, status (optional: options array of strings or {name, color, description})
date, checkbox, url, email, phone
formula (required: expression, for example "prop("Count") * 2")
rollup (required: function, relation_property, rollup_property)
relation (required: data_source_id; optional: relation_type "single_property" or "dual_property", synced_property_name)
unique_id (optional: prefix, for example "ENG")
people, files
created_time, last_edited_time, created_by, last_edited_by
verification, place, location, button
Unknown property types fail with an explicit error. No silent drops.
Inputs: title (required), schema (required), parent_page_id (required), is_inline.
create_pageA
Create a Notion page from markdown as native Notion blocks. Server handles 100-block batching, 2000-char splitting, and deep nesting, so no pre-chunking. Supports stdio-only file:// uploads. Syntax: easy-notion://docs/markdown. Mentions: @Title. Returns { id, title, url, success: true }, note for workspace-parent pages, plus block_map for top-level created blocks when present.
Inputs: title (required), markdown (required), icon, cover, +4 more.
create_page_from_fileA
Create a Notion page from a local markdown file. The server reads and validates the file, then creates the same result as create_page without sending file contents through the agent context. The server converts the markdown to native Notion blocks (not flat text) and automatically handles Notion's limits (100-block batching, 2000-char splitting, deep nesting), so large files need no pre-chunking.
STDIO MODE ONLY. This tool is not available when the server runs over HTTP, because in HTTP mode the server's filesystem belongs to the server host, not the caller.
Restrictions:
file_path must be an ABSOLUTE path (no relative paths, no ~ expansion)
File must be inside the configured workspace root (defaults to the server's process.cwd(); override via the NOTION_MCP_WORKSPACE_ROOT env var)
File extension must be .md or .markdown
File size must be ≤ 1 MB (1,048,576 bytes)
File must be valid UTF-8
Symlinks are resolved and the resolved path must still be inside the workspace root
For supported markdown syntax, read resource easy-notion://docs/markdown. Page mentions: @Title. Returns: { id, title, url, success: true }, plus note only when created as a private workspace page, plus block_map for top-level created blocks when present.
Inputs: title (required), file_path (required), parent_page_id, return_block_map, +2 more.
create_viewA
Create a Notion database view. Pass database_id. Dashboard views and dashboard widget placement are not supported.
Inputs: name (required), type (required), database_id (required), sorts, +4 more.
delete_database_entryB
Delete (archive) a database entry.
Inputs: page_id (required), dry_run.
delete_viewA
Delete a Notion database view. Destructive: confirm must be exactly true.
Inputs: view_id (required), confirm, dry_run.
duplicate_pageA
Duplicate a page. Reads all blocks from the source and creates a new page with the same content that this server can represent. If the source contains block types this server does not yet support (e.g. child_page subpages, synced_block, child_database, link_to_page), those are omitted from the duplicate AND listed in a warnings field with code omitted_block_types. Notion AI meeting notes are duplicated as ordinary toggle/heading/paragraph blocks (summary and notes only — transcripts are not duplicated); a read_only_block_rendered warning is emitted to identify meeting-notes blocks whose native identity was not preserved across the duplicate. Deep-duplication of subpages is not yet supported.
Inputs: page_id (required), title, parent_page_id.
find_replaceA
Find and replace text on a page. Preserves uploaded files and blocks that aren't touched. More efficient than replace_content for targeted text changes like fixing typos, updating URLs, or renaming terms.
Inputs: find (required), page_id (required), replace (required), dry_run, +1 more.
get_configA
Report this server's own settings: version, transport, the workspace root that bounds create_page_from_file file paths, and how many tools are visible. Call this when a file-path or configuration error occurs and you need the server's actual settings rather than a guess. Read-only, makes no Notion API call, and never returns credentials. Returns { version, transport, workspace_root_configured, workspace_root_resolved, workspace_root_status, workspace_root_source, markdown_docs, visible_tools_count }.
Inputs: no named parameters.
get_databaseA
Get a database's schema — property names, types, and select/status options. Call this before query_database or add_database_entry to know the exact property names and valid values.
Inputs: page_id, database_id.
get_meA
Get the current bot user.
Inputs: no named parameters.
get_viewA
Retrieve one Notion database view by ID. Returns a curated summary (id, name, type, url, data_source_id); set include_config: true for the full raw Notion view object.
Inputs: view_id (required), include_config.
list_commentsB
List comments on a page.
Inputs: page_id (required).
list_databasesA
List all databases the integration can access. Returns database names and IDs — use get_database on any result to see its schema.
Inputs: no named parameters.
list_pagesA
List child pages under a parent page. Each row returns id, title, created_time, and last_edited_time. Timestamps are full ISO-8601 values from Notion, rounded to the minute, and last_edited_time advances on page content and property edits.
Inputs: parent_page_id (required).
list_usersB
List workspace users.
Inputs: no named parameters.
list_viewsA
List Notion database views. Pass exactly one of database_id or data_source_id. Returns a curated summary of each view (id, name, type, url, data_source_id) plus pagination cursors; set include_config: true for the full raw Notion view objects.
Inputs: page_size, database_id, start_cursor, data_source_id, +1 more.
move_pageB
Move a page to a new parent page.
Inputs: page_id (required), new_parent_id (required).
query_databaseA
Query a database with optional filters, sorts, or text search. Use text for simple keyword search across title, rich_text, url, email, and phone fields. For advanced filters, pass Notion filter syntax and call get_database first to see property names and valid options.
Response shape: { results: Array, warnings?: Array }. Multi-value properties are capped by max_property_items and can emit truncated_properties; read resources easy-notion://docs/property-pagination and easy-notion://docs/warnings for details.
Inputs: text, sorts, filter, page_id, +2 more.
query_viewB
Query a Notion database view. Creates a temporary view query, fetches database row results, then deletes the query.
Inputs: view_id (required), page_size, start_cursor.
read_blockA
Read one block by ID as markdown. Container blocks are fetched recursively with children. Unsupported root block types return a clear error; unsupported nested blocks are omitted and listed in warnings. Notion AI meeting-notes blocks encountered in the result are rendered as a synthetic toggle and produce a read_only_block_rendered warning. Transcripts are not included from these tools.
Inputs: block_id (required).
read_pageA
Read a page and return metadata plus markdown. Recursively fetches nested blocks and uses the same markdown conventions accepted by create_page. If unsupported block types are omitted from the markdown, they are listed in warnings. Do NOT round-trip markdown through replace_content when omitted_block_types warnings are present; omitted blocks would be deleted.
Notion AI meeting notes are rendered as a synthetic toggle containing the title, an optional recording timestamp callout, and ## Summary / ## Notes heading sections. Transcript sections are included only with include_transcript: true. A read_only_block_rendered warning is emitted whenever such a block is rendered, indicating that round-tripping the markdown through replace_content will replace the native meeting-notes block with ordinary blocks.
Note on max_blocks: the cap counts top-level page blocks only; section descendants of meeting-notes blocks are fetched in full regardless of the cap, consistent with how nested children of normal blocks are fetched.
Long titles are paginated with max_property_items. For markdown conventions, warning shapes, and pagination details, read resources easy-notion://docs/markdown, easy-notion://docs/warnings, and easy-notion://docs/property-pagination.
Inputs: page_id (required), max_blocks, include_metadata, include_transcript, +1 more.
read_sectionA
Read a single page section by heading name. Uses the same heading matching and boundary rules as update_section: headings are matched case-insensitively, H1 sections end at the next heading of any level, and H2/H3 sections end at the next heading of the same or higher level. Includes the heading block itself and recursively renders nested children only for blocks inside the selected section. If unsupported nested block types are omitted, the response includes warnings. Notion AI meeting-notes blocks encountered in the result are rendered as a synthetic toggle and produce a read_only_block_rendered warning. Transcripts are not included from these tools.
Inputs: heading (required), page_id (required).
read_toggleA
Read one toggle by title from a page. Searches recursively and matches plain toggle blocks plus toggleable heading_1, heading_2, and heading_3 blocks using case-insensitive trimmed text. Missing titles return the available toggle titles. Notion AI meeting-notes blocks encountered in the result are rendered as a synthetic toggle and produce a read_only_block_rendered warning. Transcripts are not included from these tools.
Inputs: title (required), page_id (required).
replace_contentA
Replaces all page content with the provided markdown atomically (one Notion API call). Notion's atomic markdown endpoint converts the markdown to native Notion blocks in that one API call. On matched blocks Notion preserves the original block IDs, so deep-link anchors (#block-id) and inline-comment threads attached to those blocks survive the edit. Unmatched blocks (returned in warnings with code unmatched_blocks) are replaced with new IDs.
NOT preserved across replace_content: child_page subpages, synced_block instances, child_database views, and link_to_page references on the source page. Enhanced Markdown has no input form for these, so they are dropped from the new page content. If the source contains them, use duplicate_page first or edit those types via the Notion UI. For an inline page mention, use @Title; that is a separate construct from the link_to_page block type.
Bookmarks and embeds are written as bare URLs (Notion auto-links) and surface a bookmark_lost_on_atomic_replace or embed_lost_on_atomic_replace warning so callers know the rich preview is lost. For supported markdown syntax and warning details, read resources easy-notion://docs/markdown and easy-notion://docs/warnings. Returns: { success: true }, optionally truncated: true, optionally warnings with entries such as { code: "unmatched_blocks", block_ids: [...] }, plus block_map for the resulting top-level blocks when present. A dry run returns { success: true, dry_run: true, operation, page_id, would_update: true } and optionally warnings.
Inputs: page_id (required), markdown (required), dry_run, return_block_map, +1 more.
restore_pageA
Restore an archived page.
Inputs: page_id (required).
restore_toggleA
Restore an archived toggle or toggleable heading by archived block ID. Use the block ID returned by archive_toggle; Notion does not expose archived child enumeration for title search or read_page include_archived.
Inputs: block_id (required), dry_run.
searchA
Search Notion pages or databases. Use filter: 'databases' to find databases by name, then get_database for schema details.
Inputs: query (required), filter.
search_in_pageA
Search raw Notion block plain text inside a page, optionally scoped to one toggle or toggleable heading by title. Matching is case-insensitive plain substring search.
Inputs: query (required), page_id (required), within_toggle.
update_blockA
Update a single block in place by ID. Preserves the block's identity (deep-link anchors and inline-comment threads attached to the block survive the edit). Use this for surgical edits: fixing a heading, toggling a checkbox, rewriting one paragraph. For multi-block edits, use append_content, replace_content, or update_section.
Type lock-in: the markdown must parse to the same block type as the existing block. update_block cannot change a block's type, because Notion's API forbids it. To change a block's type, use replace_content or delete + append.
Updatable types: paragraph, heading_1, heading_2, heading_3, toggle, bulleted_list_item, numbered_list_item, quote, callout, to_do, code, equation. Container blocks (toggle, callout) update first-level content only, and children stay untouched. Non-updatable types (divider, table, image, bookmark, etc.) accept only archived: true to delete the block. Page mentions: @Title.
To delete a block, pass archived: true instead of markdown. Exactly one of markdown or archived is required.
Inputs: block_id (required), checked, dry_run, archived, +2 more.
update_database_entryA
Update an existing database entry using simple key-value property inputs. Pass only properties to change; omitted properties are left unchanged. Call get_database first to see available property names and valid select/status options.
Writable property values use the same simple inputs as add_database_entry:
title, rich_text: string
number: number
select, status: option name string
multi_select: array of option name strings
date: ISO date string (start only)
checkbox: boolean
url, email, phone: string
relation: string or array of page IDs
people: string or array of user IDs
Not writable from this tool:
formula, rollup, unique_id, created_time, last_edited_time, created_by, last_edited_by: computed by Notion
files, verification, place, location, button: not supported for value writes here
Inputs: page_id (required), properties (required).
update_data_sourceA
CRITICAL: full-list semantics. When you update a select or status property's options array, you MUST send the full desired list. Any existing option you omit will be permanently removed from the database, along with any relationship to rows currently using it. Rows that currently reference a removed option are silently reassigned to the default group's first option (for example "Not started" for status properties). No signal is raised. If you want to preserve the meaning of existing rows when removing an option, reclassify those rows to another explicit option before removing the option from the schema. To add one option, first call get_database, then resend the full current list with your addition appended.
Cannot toggle is_inline on existing databases. is_inline is a database-level field, not a data-source field. A separate update_database tool may be added later.
Updates a database's schema: rename properties, add or update property definitions, remove properties, change the title, or move it to/from trash. Use after get_database. Supports raw Notion payloads and schema helper payloads; read resource easy-notion://docs/update-data-source for modes, examples, status notes, and limitations. At least one of title, properties, or in_trash must be provided.
Inputs: title, page_id, in_trash, properties, +1 more.
update_pageA
Update page title, icon, or cover. Cover accepts an image URL, or a file:// path (stdio transport only) which will be uploaded to Notion. In HTTP transport, the file:// form is rejected — use an HTTPS URL instead.
Inputs: page_id (required), icon, cover, title.
update_sectionA
DESTRUCTIVE, no rollback: this tool deletes blocks in the section, then writes new blocks. If the write fails mid-call, the section is left partially or fully emptied; for most sections the heading anchor is deleted, so a retry can fail with "heading not found." For irreplaceable sections, duplicate_page the target first so you have a restore point.
Update a section of a page by heading name. Finds the heading, replaces everything from that heading to the next section boundary. For H1 headings, the section extends to the next heading of any level. For H2/H3 headings, it extends to the next heading of the same or higher level. Include the heading itself in the markdown. If the section starts at the first block, the replacement markdown must start with the same heading type so following sections stay in place. With preserve_heading:true, the existing heading block ID, text, type, comments, and toggleable state are preserved, but the section body blocks and existing toggleable-heading children are still destructively replaced; replacement markdown is treated as body-only, and a leading matching heading is stripped for compatibility. More efficient than replace_content for editing one section of a large page. Page mentions: @Title. Returns { deleted, appended }, plus deleted_blocks for the deleted top-level blocks when present and block_map for the top-level appended blocks when present. A dry run instead returns { success: true, dry_run: true, operation, page_id, heading, target_block_id, target_block_type, preserve_heading, deleted, appended, would_delete_block_ids, append_parent_id }, plus append_after_block_id when the append is anchored to a preceding block, and would_update with would_update_block_id when the heading block itself is rewritten.
Inputs: heading (required), page_id (required), markdown (required), dry_run, +3 more.
update_toggleA
DESTRUCTIVE, no rollback: this tool preserves the matched toggle container block ID, then deletes its body children and appends replacement body blocks. Child block IDs inside the body change, and if the write fails mid-call the toggle can be left partially or fully emptied. For irreplaceable content, duplicate_page the target first so you have a restore point.
Update the body of one toggle by title from a page. Searches recursively and matches plain toggle blocks plus toggleable heading_1, heading_2, and heading_3 blocks using case-insensitive trimmed text. The markdown is replacement body content, not a wrapper that renames the toggle, and the server converts it into native Notion blocks, not flat/plain text. The server automatically handles Notion API limits: batches more than 100 child blocks, splits rich text over 2000 characters, and writes deeply nested blocks in additional passes, so callers can send a full multi-section toggle tree in one call with no need to pre-chunk or pre-split. If the markdown parses as one matching top-level toggle or toggleable heading wrapper, that wrapper is ignored and only its children are used as the replacement body. For supported markdown syntax, read resource easy-notion://docs/markdown. Page mentions: @Title. Returns: { success: true, block_id, type, deleted, appended }, where deleted and appended are counts, plus deleted_blocks for the deleted top-level body blocks when present and block_map for the top-level appended body blocks when present. A dry run instead returns { success: true, dry_run: true, operation, page_id, title, block_id, type, deleted, appended, would_delete_block_ids, append_parent_id }.
Inputs: title (required), page_id (required), markdown (required), dry_run, +2 more.
update_viewA
Update a Notion database view. Pass at least one update field. Null filter, sorts, or quick_filters values are forwarded to clear those fields.
Inputs: view_id (required), name, sorts, filter, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 43 tools
Most tools are clearly distinct by resource (page, block, toggle, database, view, comment, user). Some potential confusion exists between update_section/update_toggle/update_block and read_section/read_block/read_toggle, but descriptions clarify the target granularity. The pair add_database_entry/add_database_entries is intentionally similar but the plural is self-explanatory.
The set predominantly uses verb_noun naming (create_page, read_page, update_page, archive_page, restore_page, query_database, add_database_entry, delete_database_entry). Minor deviations exist: get_view vs list_views, get_database vs list_databases, and get_me/get_config don't follow the verb_noun pattern, but the overall convention is consistent and predictable.
43 tools is on the heavy side for a single MCP server, but the breadth roughly matches Notion's feature surface (pages, blocks, toggles, databases, views, comments, users). The count is justified by the domain, though it approaches the upper bound where navigation becomes burdensome.
The tool surface covers the full lifecycle for pages (create, read, update, archive, restore, duplicate, move), blocks (read, update, delete, append, replace), toggles (read, update, archive, restore), databases (create, get, list, query, update schema, add/update/delete entries), views (list, create, update, delete), comments, and users. Notable gaps like subpage deep-duplication and database inline toggling are explicitly documented as limitations rather than missing coverage.
Maintenance
Related MCP Connectors
Hosted Notion MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Related MCP Servers
- AlicenseAqualityAmaintenanceMarkdown-first MCP server for Notion that provides 7 composite action-based tools consolidating 28+ REST API endpoints, enabling AI agents to efficiently manage pages, databases, blocks, and content with automatic pagination and bulk operations.101,730 npm36Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that enables LLMs to interact with Notion workspaces via the Notion API, supporting page creation, database management, and content retrieval. It features markdown conversion to optimize token usage and enhanced error handling for more reliable workspace interactions.191MIT
- AlicenseAqualityDmaintenanceA lightweight Notion MCP server that minimizes token usage by returning Markdown instead of raw JSON, enabling efficient read/write operations on Notion pages.9MIT
- AlicenseNot gradedqualityDmaintenanceStateless MCP server exposing the full Notion API as 33 tools, enabling users to manage pages, databases, blocks, comments, users, and file uploads using their own integration token.Apache 2.0