MCP SERVERFind, read and edit Notion pages and data sources — with responses compact enough to keep working in.
LABSCO SUMMARY
Find, read, inspect, then write is the sequence the tools are built around, and it is the one that avoids guessing at property JSON. The allowlist argument is worth knowing about: it is how you hand an agent a Notion workspace it can read and not touch.
A Notion client built for agents rather than for API completeness. Simplified tools cover the common path — find a target, read a page, inspect a data source, query it and write back — while the raw API tools stay available underneath for shapes the simple ones do not cover. It targets the current Notion API version and its database and data source model.
Node.js 22 or newer, run over stdio from npm as @suekou/mcp-notion-server, with NOTION_API_TOKEN set to an internal integration token. Access in Notion is explicit twice over: the integration is granted only the capabilities you tick — read, insert, update, comments, user information — and it can only see the pages and databases you have connected it to, children included. The token is sent as a bearer header against a pinned API version. Markdown conversion of API objects is experimental and off unless NOTION_MARKDOWN_CONVERSION is set. An --enabledTools allowlist restricts which tools are registered at all, which is how you make the server read-only.
One command plus a key — npx -y @suekou/mcp-notion-server, then supply credentials
USE CASES
Find the page, read it compactly, and work from what it says rather than from a search snippet.
Append the Markdown or the structured blocks, then correct a specific block using the ID the read returned.
Inspect the schema first so the fields are right, then create the item from plain values instead of property JSON.
Query by field values for the everyday case, or fall back to the full query when the filter is more than that.
Batch the content updates rather than issuing one call per block, after reading the children to get their IDs.
Comment on the page and read the existing thread, if the integration was granted comment access.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
notion_append_block_childrenAppend new children blocks to a specified parent block in Notion. Requires insert content capabilities. Use the optional 'position' object to insert at the start, end, or after a specific block.
notion_append_contentAppend common Notion content without writing raw Notion block JSON. Use this for everyday page editing when the user wants to add paragraphs, headings, lists, todos, quotes, callouts, code blocks, or dividers. For unsupported block types or advanced rich text annotations, use notion_append_block_children with raw Notion block objects.
notion_append_markdownAppend a safe subset of Markdown to a Notion page or block without writing raw Notion block JSON. Supports headings (#, ##, ###), paragraphs, bullet items, numbered items, todos (- [ ] / - [x]), quotes, dividers, and fenced code blocks. Use this when the user provides Markdown-like content and wants it appended; use raw block tools for tables, images, rich text annotations, nested lists, or advanced Notion blocks.
notion_create_commentCreate a comment in Notion. This requires the integration to have 'insert comment' capabilities. You can either specify a page parent or a discussion_id, but not both.
notion_create_data_sourceAdd an additional Notion data source to an existing database. Do not use this to create a new database; use notion_create_database for that.
notion_create_data_source_itemCreate a new page item in a Notion data source. Use the data_source_id, not the database_id, as the parent.
notion_create_data_source_item_from_valuesCreate a new page item in a Notion data source using simple property values instead of raw Notion property JSON. The server retrieves the data source schema and converts common property types for you: title, rich_text, number, checkbox, select, status, multi_select, date, url, email, phone_number, relation, and people. Use notion_inspect_data_source first when you need valid property names or option values.
notion_create_databaseCreate a Notion database and its initial data source. Use this when the user wants a new database. For Notion API 2025-09-03+, put the initial schema under initial_data_source.properties.
notion_delete_blockDelete a block in Notion
notion_findFind Notion pages or data sources and return compact, AI-friendly candidates with stable IDs and suggested next tools. Use this before low-level retrieve/query tools when the user gives a title, partial name, or vague target. Prefer this over raw notion_search for discovery because it trims noisy API fields and highlights the IDs needed for the next action.
notion_inspect_data_sourceInspect a Notion data source schema and return a compact property summary for AI agents. Use this before creating or updating items so the model can choose valid property names, option values, and relation targets without reading the full Notion API object.
notion_list_all_usersList all users in the Notion workspace. Note: This function requires upgrading to the Notion Enterprise plan and using an Organization API key to avoid permission errors.
notion_open_data_source_appOpen an interactive Notion Data Source Explorer MCP App for schema inspection, filter building, querying, and item creation from simple values.
notion_open_page_workbenchOpen an interactive Notion Page Workbench MCP App for reading page content, selecting block IDs, updating simple blocks, and appending Markdown.
notion_query_data_sourceQuery a Notion data source with filters, sorts, and pagination. Use notion_retrieve_database first when you only have a database ID and need to discover its data_source_id.
notion_query_data_source_by_valuesQuery a Notion data source using simple schema-aware filters and sorts instead of raw Notion filter JSON. Use this after notion_inspect_data_source when the user asks for common queries like Status equals Done, Tags contains AI, Due on or before a date, Estimate greater than 3, or Done equals false. The server validates property names, option names, value types, and supported operators before calling Notion.
notion_read_pageRead a Notion page with compact page metadata plus block content in an AI-friendly outline or Markdown shape. Use this after notion_find when you need to understand or edit a page. It fetches child blocks with max_depth and max_blocks limits so large pages do not overwhelm the model. The outline includes stable block IDs that can be used with notion_append_content position.after_block.
notion_retrieve_blockRetrieve a block from Notion
notion_retrieve_block_childrenRetrieve the children of a block
notion_retrieve_bot_userRetrieve the bot user associated with the current token in Notion
notion_retrieve_commentsRetrieve a list of unresolved comments from a Notion page or block. Requires the integration to have 'read comment' capabilities.
notion_retrieve_data_sourceRetrieve metadata and property schema for a Notion data source.
notion_retrieve_databaseRetrieve a Notion database container and its child data_sources. Use this to discover which data_source_id should be used for query, schema, and item creation operations.
notion_retrieve_pageRetrieve a page from Notion
notion_retrieve_userRetrieve a specific user by user_id in Notion. Note: This function requires upgrading to the Notion Enterprise plan and using an Organization API key to avoid permission errors.
notion_searchSearch pages or data sources by title in Notion
notion_update_blockUpdate the content of a block in Notion based on its type. The update replaces the entire value for a given field.
notion_update_contentUpdate an existing Notion block without writing raw Notion block JSON. Use this after notion_read_page gives you a block ID and you need to replace the text or simple fields of an existing paragraph, heading, list item, todo, quote, callout, or code block. The item.type must match the block's current type; this tool will reject mismatches so the model can correct itself.
notion_update_content_batchUpdate multiple existing Notion blocks without writing raw Notion block JSON. Use this after notion_read_page when the user wants several simple text edits at once. The server retrieves every target block and validates all item.type values before applying updates, so block type mistakes fail before any write is attempted.
notion_update_data_sourceUpdate a Notion data source title, description, or properties.
notion_update_page_propertiesUpdate properties of a page or an item in a Notion database
BEFORE YOU INSTALL
31 tools when we connected. --enabledTools takes a comma-separated allowlist; the documented read-only example cuts the set to 14. notion_list_all_users and notion_retrieve_user can require a Notion Enterprise plan and an Organization API key.
CONTEXT COST
Rated by the size of the 31 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
npx -y @suekou/mcp-notion-server{
"mcpServers": {
"notion": {
"command": "npx",
"args": [
"-y",
"@suekou/mcp-notion-server"
],
"env": {
"NOTION_API_TOKEN": "<YOUR_NOTION_API_TOKEN>"
}
}
}
}git clone https://github.com/suekou/mcp-notion-server
cd mcp-notion-server
pnpm install --frozen-lockfile
pnpm run build{
"mcpServers": {
"notion": {
"command": "node",
"args": [
"<YOUR_PATH_TO_MCP_NOTION_SERVER>/build/index.js"
],
"env": {
"NOTION_API_TOKEN": "<YOUR_NOTION_API_TOKEN>"
}
}
}
}MCP servers
Shameerpc5029
GaoZYun
awkoy
orbit-logistics