Notion MCP Server
The Notion MCP Server acts as an intermediary that enables LLMs to interact with Notion workspaces via API. It offers comprehensive content management capabilities:
Content Operations:
Read/Retrieve: Fetch blocks, pages, databases, users, and comments
Create/Modify: Append, update, or delete blocks; update page properties; create database items
Database Management: Create, query, and update databases with filters and sorting
Search: Find pages or databases by title
Comments: Create comments and retrieve unresolved discussions
User Management: List workspace users and retrieve user information (requires Enterprise plan)
Configuration Options:
Convert responses to Markdown format to optimize token usage and improve readability
Enable specific tools and customize response formats for tailored interactions
Allows Claude to interact with Notion workspaces through the Notion API, including manipulating blocks, pages, databases, retrieving user information, and creating comments
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Notion MCP Server find my meeting notes from last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Notion MCP Server
AI-friendly MCP server for the Notion API. It helps agents find, read, query, and update Notion workspaces while keeping responses compact enough for day-to-day AI workflows.
This server targets the Notion API 2026-03-11 and uses the current database/data source model. It exposes MCP tools, prompts, resources, structured tool results, and optional MCP Apps for interactive Notion workflows.
Highlights
Search and target discovery with
notion_find.Compact page reading with stable block IDs via
notion_read_page.Data source schema inspection with
notion_inspect_data_source.Schema-aware data source querying and item creation with simple values.
Simple page editing tools for paragraphs, headings, lists, todos, quotes, callouts, code blocks, dividers, and safe Markdown append.
Raw Notion API tools for advanced block, page, database, data source, comment, and user operations.
Optional MCP Apps: Data Source Explorer and Page Workbench.
Related MCP server: MCP Notion Server (@suncreation)
Quick Start
Add this server to an MCP host such as Claude Desktop:
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@suekou/mcp-notion-server"],
"env": {
"NOTION_API_TOKEN": "your-integration-token"
}
}
}
}Restart your MCP host after saving the configuration.
Setup Guide
1. Create a Notion integration
Open the Notion integrations dashboard, then create a new internal integration.

2. Configure capabilities
Grant only the capabilities you need:
Read content: required for search, page reads, data source retrieval, and queries.
Insert content: required for creating pages/items and appending blocks.
Update content: required for updating pages, blocks, and data source schemas.
Read comments / Insert comments: required only for comment tools.
User information: required only when using user lookup tools.
For full functionality during setup, enable read, insert, and update content. Add comment or user capabilities only if you plan to use those tools.

3. Grant content access
Open the Content access tab for your integration, then select the pages or databases you want the MCP server to read or edit.
You can also grant access from the target Notion page or database: open the ... menu, choose Connections, then add your integration.
Notion only lets an integration access pages and databases that have been shared with it. A connection added to a page can also access that page's children.

4. Copy the internal integration token
Copy the integration secret. This value becomes NOTION_API_TOKEN in your MCP host config.

5. Configure your MCP host
For Cursor, Claude Desktop, and other MCP hosts, add this server config to your MCP settings:
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@suekou/mcp-notion-server"],
"env": {
"NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}For a locally built checkout:
{
"mcpServers": {
"notion": {
"command": "node",
"args": ["/absolute/path/to/suekou-mcp-notion-server/build/index.js"],
"env": {
"NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}Recommended Workflow
Use
notion_findto locate a page or data source.Use
notion_read_pagefor page context and editable block IDs.Use
notion_inspect_data_sourcebefore querying or creating data source items.Use
notion_query_data_source_by_valuesandnotion_create_data_source_item_from_valuesfor common data source work.Use
notion_append_markdown,notion_append_content,notion_update_content, ornotion_update_content_batchfor normal page edits.Fall back to raw JSON tools only when the simplified tools do not cover the Notion API shape you need.
For Developers
These references are mainly for development, customization, and advanced MCP workflows:
Configuration: environment variables, command-line arguments, MCP host examples, development commands, and troubleshooting.
Tools: complete tool reference grouped by workflow area.
Workflows: practical read, write, data source, migration, and error-handling guidance.
MCP Apps: interactive Data Source Explorer and Page Workbench details.
Development
This project uses Node.js 22 or newer and pnpm.
pnpm install --frozen-lockfile
pnpm run build
pnpm testUse the MCP inspector during local development:
pnpm run inspectorLicense
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
Available Tools
31 toolsnotion_append_block_childrenAppend Block ChildrenA
Append 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.
Inputs: block_id (required), children (required), format, position.
notion_append_contentAppend Simple ContentA
Append 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.
Inputs: items (required), block_id (required), format, position.
notion_append_markdownAppend Markdown ContentA
Append 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.
Inputs: block_id (required), markdown (required), format, position.
notion_create_commentCreate CommentA
Create 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.
Inputs: rich_text (required), format, parent, discussion_id.
notion_create_databaseCreate DatabaseA
Create 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.
Inputs: parent (required), initial_data_source (required), icon, cover, +4 more.
notion_create_data_sourceCreate Data SourceA
Add an additional Notion data source to an existing database. Do not use this to create a new database; use notion_create_database for that.
Inputs: parent (required), properties (required), title, format.
notion_create_data_source_itemCreate Data Source ItemB
Create a new page item in a Notion data source. Use the data_source_id, not the database_id, as the parent.
Inputs: properties (required), data_source_id (required), format.
notion_create_data_source_item_from_valuesCreate Item From ValuesA
Create 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.
Inputs: values (required), data_source_id (required), format.
notion_delete_blockDelete BlockBDestructiveIdempotent
Delete a block in Notion
Inputs: block_id (required), format.
notion_findFind Notion TargetsARead-only
Find 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.
Inputs: query, format, page_size, object_type, +1 more.
notion_inspect_data_sourceInspect Data SourceARead-only
Inspect 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.
Inputs: data_source_id (required), format.
notion_list_all_usersList UsersARead-only
List 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.
Inputs: format, page_size, start_cursor, response_mode.
notion_open_data_source_appOpen Data Source ExplorerB
Open an interactive Notion Data Source Explorer MCP App for schema inspection, filter building, querying, and item creation from simple values.
Inputs: format, data_source_id.
notion_open_page_workbenchOpen Page WorkbenchB
Open an interactive Notion Page Workbench MCP App for reading page content, selecting block IDs, updating simple blocks, and appending Markdown.
Inputs: format, page_id.
notion_query_data_sourceQuery Data SourceARead-only
Query 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.
Inputs: data_source_id (required), sorts, filter, format, +3 more.
notion_query_data_source_by_valuesQuery Data Source By ValuesARead-only
Query 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.
Inputs: data_source_id (required), match, sorts, format, +4 more.
notion_read_pageRead Page ContentARead-only
Read 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.
Inputs: page_id (required), format, max_depth, page_size, +3 more.
notion_retrieve_blockRetrieve BlockBRead-only
Retrieve a block from Notion
Inputs: block_id (required), format.
notion_retrieve_block_childrenRetrieve Block ChildrenBRead-only
Retrieve the children of a block
Inputs: block_id (required), format, page_size, start_cursor, +1 more.
notion_retrieve_bot_userRetrieve Bot UserARead-only
Retrieve the bot user associated with the current token in Notion
Inputs: format.
notion_retrieve_commentsRetrieve CommentsARead-only
Retrieve a list of unresolved comments from a Notion page or block. Requires the integration to have 'read comment' capabilities.
Inputs: block_id (required), format, page_size, start_cursor, +1 more.
notion_retrieve_databaseRetrieve DatabaseARead-only
Retrieve 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.
Inputs: database_id (required), format.
notion_retrieve_data_sourceRetrieve Data SourceARead-only
Retrieve metadata and property schema for a Notion data source.
Inputs: data_source_id (required), format.
notion_retrieve_pageRetrieve PageBRead-only
Retrieve a page from Notion
Inputs: page_id (required), format.
notion_retrieve_userRetrieve UserARead-only
Retrieve 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.
Inputs: user_id (required), format.
notion_searchSearch NotionBRead-only
Search pages or data sources by title in Notion
Inputs: sort, query, filter, format, +3 more.
notion_update_blockUpdate BlockAIdempotent
Update the content of a block in Notion based on its type. The update replaces the entire value for a given field.
Inputs: block (required), block_id (required), format.
notion_update_contentUpdate Simple ContentAIdempotent
Update 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.
Inputs: item (required), block_id (required), format.
notion_update_content_batchUpdate Simple Content BatchAIdempotent
Update 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.
Inputs: updates (required), format.
notion_update_data_sourceUpdate Data SourceAIdempotent
Update a Notion data source title, description, or properties.
Inputs: data_source_id (required), title, format, properties, +1 more.
notion_update_page_propertiesUpdate Page PropertiesBIdempotent
Update properties of a page or an item in a Notion database
Inputs: page_id (required), properties (required), format.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 31 tools
There is notable overlap among tools like notion_append_content, notion_append_markdown, notion_append_block_children, and also between notion_update_content and notion_update_block. While descriptions attempt to differentiate them, an agent might struggle to choose between raw and high-level versions, and between retrieve_block and read_page.
All tools follow a consistent verb_noun pattern using snake_case, e.g., notion_append_block_children, notion_retrieve_block, notion_create_data_source. The prefix 'notion_' is consistent, and verbs like retrieve, create, update, append, delete are used uniformly.
With 31 tools, the server is on the heavier side but still within a manageable range because the domain (Notion) is broad and requires separate tools for pages, blocks, data sources, comments, users, and discovery. The count is slightly high but each tool handles a distinct resource or operation.
The tool set covers a comprehensive lifecycle for pages, blocks, data sources, comments, and users, including creation, retrieval, updating, deletion, and search. Higher-level convenience tools (e.g., notion_append_markdown, notion_query_data_source_by_values) are complemented by lower-level raw tools, providing no obvious dead ends for common workflows.
Maintenance
Related MCP Connectors
Hosted Notion MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceAn MCP server that enables natural language interaction with the Notion API, allowing users to search, comment, create pages, and access content within their Notion workspace.282,573 npm-
- 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
- AlicenseNot gradedqualityDmaintenanceMCP server for the Notion API, enabling management of pages, blocks, databases, data sources, comments, and users through natural language.12 npm3MIT
- AlicenseBqualityDmaintenanceNotion API MCP server for Claude Code to manipulate Notion pages, blocks, and databases with batch operations and Windows compatibility.5MIT