@Grey-Iris
Basic information
Markdown-first Notion MCP server — 26 tools, 92% fewer tokens, full round-trip fidelity
Add this server to your MCP-compatible client using the configuration below.
{
"mcpServers": {
"notion": {
"command": "npx",
"args": [
"-y",
"easy-notion-mcp"
],
"env": {
"NOTION_TOKEN": "ntn_your_integration_token"
}
}
}
}Create a Notion page from markdown, converted server-side to native Notion blocks (not flat text). The server auto-handles Notion's limits (100-block batching, 2000-char splitting, deep nesting); send large trees in one call, no pre-chunking. Supports stdio-only file:// uploads. Syntax guide: resource easy-notion://docs/markdown. Returns { id, title, url } only (no block count or per-block IDs).
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. Returns: { id, title, url }, plus note only when created at the workspace root. There is no block count and no per-block IDs in the receipt.
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. Returns: { success: true, blocks_added: <number> }.
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. Bookmarks and embeds round-trip as bare URLs (Notion auto-links) and surface a `bookmark_lost_on_atomic_replace` warning so callers know the rich-bookmark UI 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: [...] }.
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.
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.
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.
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.
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.
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.
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. Returns: { success: true, block_id, type, deleted, appended }, where deleted and appended are counts.
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.
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.
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 — 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 — children stay untouched. Non-updatable types (divider, table, image, bookmark, etc.) accept only `archived: true` to delete the block. To delete a block, pass `archived: true` instead of `markdown`. Exactly one of `markdown` or `archived` is required.
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.
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.
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.
Archive a page in Notion.
Search Notion pages or databases. Use filter: 'databases' to find databases by name, then get_database for schema details.
List child pages under a parent page.
Return the page URL that can be shared from Notion.
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.
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.
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.
List all databases the integration can access. Returns database names and IDs — use get_database on any result to see its schema.
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<entry>, warnings?: Array<warning> }. 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.
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.
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.
Query a Notion database view. Creates a temporary view query, fetches database row results, then deletes the query.
Create a Notion database view. Pass database_id. Dashboard views and dashboard widget placement are not supported.
Update a Notion database view. Pass at least one update field. Null filter, sorts, or quick_filters values are forwarded to clear those fields.
Delete a Notion database view. Destructive: confirm must be exactly true.
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"] }.
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.
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
List comments on a page.
Add a comment to a page.
Move a page to a new parent page.
Restore an archived page.
Delete (archive) a database entry.
List workspace users.
Get the current bot user.
Easy Notion Mcp is a markdown-first MCP server that connects AI agents to Notion. It converts standard GFM markdown to Notion's block API and back, supporting 26 tools and 25 block types with full round-trip fidelity.
Install via npx easy-notion-mcp. Use OAuth (HTTP server with npx easy-notion-mcp-http) or an API token (NOTION_TOKEN). Configure with any MCP client (Claude Code, Claude Desktop, OpenClaw, Cursor, VS Code Copilot, Windsurf). The server runs on stdio (API token) or HTTP (OAuth).
file:///path in markdown.Easy Notion Mcp uses standard GFM markdown, supports 25 block types, offers 26 tools, and achieves full round-trip fidelity – unlike the official server (raw JSON) or better-notion-mcp (limited block types, dropped content).
Two options: OAuth (recommended) – run the HTTP server and connect with any MCP client; API token – create a Notion integration, set `NOTION_TOKEN`, and share pages with it. Configuration examples for Claude Desktop, Cursor, VS Code, Windsurf, and OpenClaw are provided.
It fetches the database schema at runtime and converts simple key-value pairs (e.g., `{"Status": "Done"}`) to Notion's property format automatically. Schema is cached for 5 minutes. Tools include create, query, add, update, and delete entries.
Easy Notion Mcp adds a content notice prefix to read responses and sanitizes URLs to help defend against prompt injection attacks.
Yes. All 25 supported block types (including toggles, columns, callouts, equations, tables, task lists) round-trip cleanly. Read a page as markdown, modify the string, then write it back – nothing is lost.
Shared, serverless, conflict-free memory for AI agents: a multi-machine drop-in for the MCP memory knowledge graph.
The official Semantic-UI-React integration
Open-source Python SDK & MCP interface for Priostack Agent Context Network (ACN). Zero-setup, autonomous memory orchestration for AI agents.
Exact, shared memory for AI agents: a hierarchical database where totals always add up, every write is attributed to the agent and person behind it, and any figure traces back to its source file. Agents create databases,
The ultimate RAG for your monorepo. Query, understand, and edit multi-language codebases with the power of AI and knowledge graphs
Comments