MCP Notion Server (@suncreation)
Provides comprehensive access to the Notion API, allowing for the management of pages, databases, blocks, and comments, as well as searching workspaces and retrieving user information.
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., "@MCP Notion Server (@suncreation) search for 'Project Roadmap' and summarize the content"
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.
@suncreation/mcp-notion-server
MCP Server for the Notion API, enabling LLM to interact with Notion workspaces.
Fork Notice: This is a fork of @suekou/mcp-notion-server with enhancements including improved error handling, additional features, and better environment variable support.
Features
Full Notion API integration via MCP (Model Context Protocol)
Markdown conversion to reduce token usage
Page creation (
notion_create_page) - Create new pages under existing pagesSupports both
NOTION_API_TOKENandNOTION_API_KEYenvironment variablesEnhanced error handling with detailed HTTP status code messages
Related MCP server: Notion MCP Server
Installation
npx -y @suncreation/mcp-notion-serverQuick Start
1. Create a Notion Integration
Visit the Notion Integrations page
Click "New Integration"
Name your integration and select permissions:
✅ Read content
✅ Update content
✅ Insert content
Copy the "Internal Integration Token" (starts with
ntn_orsecret_)
2. Connect Integration to Pages
Open the Notion page you want to access
Click "···" (top right) → "Connections"
Add your integration
3. Configure Your MCP Client
OpenCode
Add to ~/.config/opencode/opencode.json:
{
"mcp": {
"notion": {
"type": "local",
"command": ["npx", "-y", "@suncreation/mcp-notion-server"],
"environment": {
"NOTION_API_TOKEN": "your-integration-token"
},
"enabled": true
}
}
}Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@suncreation/mcp-notion-server"],
"env": {
"NOTION_API_TOKEN": "your-integration-token"
}
}
}
}Multiple Workspaces
You can connect multiple Notion workspaces by using different names:
{
"mcp": {
"notion-work": {
"type": "local",
"command": ["npx", "-y", "@suncreation/mcp-notion-server"],
"environment": {
"NOTION_API_TOKEN": "work-workspace-token"
},
"enabled": true
},
"notion-personal": {
"type": "local",
"command": ["npx", "-y", "@suncreation/mcp-notion-server"],
"environment": {
"NOTION_API_TOKEN": "personal-workspace-token"
},
"enabled": true
}
}
}Environment Variables
Variable | Required | Description |
| Yes* | Your Notion API integration token |
| Yes* | Alternative name for the token (either works) |
| No | Set to |
*One of NOTION_API_TOKEN or NOTION_API_KEY is required.
Available Tools
Pages
Tool | Description |
| Get page information |
| Update page properties |
| Create a new page (enhanced feature) |
Blocks
Tool | Description |
| Get block information |
| Get child blocks |
| Add blocks to a page/block |
| Delete a block |
Databases
Tool | Description |
| Create a new database |
| Query database entries |
| Get database schema |
| Update database properties |
| Add item to database |
Search & Users
Tool | Description |
| Search pages/databases by title |
| List workspace users (Enterprise) |
| Get user details (Enterprise) |
| Get bot user info |
Comments
Tool | Description |
| Add a comment |
| Get comments on a page/block |
Command Line Options
# Enable only specific tools
node build/index.js --enabledTools=notion_retrieve_page,notion_query_database
# Read-only mode example
node build/index.js --enabledTools=notion_retrieve_block,notion_retrieve_block_children,notion_retrieve_page,notion_query_database,notion_retrieve_database,notion_searchMarkdown Conversion
Enable Markdown conversion for reduced token usage:
{
"environment": {
"NOTION_API_TOKEN": "your-token",
"NOTION_MARKDOWN_CONVERSION": "true"
}
}Use
format: "markdown"for readable output (viewing)Use
format: "json"for structured data (editing)
Troubleshooting
Issue | Solution |
Permission denied | Ensure integration is added to the page via "Connections" |
401 Unauthorized | Check your API token is correct |
404 Not Found | Verify the page/database ID is correct |
Rate limited | Add delays between requests |
Development
# Clone and install
git clone https://github.com/SunCreation/mcp-notion-server.git
cd mcp-notion-server
npm install
# Build
npm run build
# Test
npm test
# Watch mode
npm run watchChanges from Original
This fork includes the following enhancements over @suekou/mcp-notion-server:
notion_create_pagetool - Create new pages under existing pagesDual environment variable support - Both
NOTION_API_TOKENandNOTION_API_KEYworkEnhanced error handling - Detailed HTTP status code messages for easier debugging
setApiVersion()method - Dynamically change API version if needed
License
MIT License - see LICENSE file.
Credits
Original project: @suekou/mcp-notion-server
Available Tools
19 toolsnotion_append_block_childrenA
Append children blocks to a parent block. LIMITS: Max 100 blocks, 2 nesting levels, 2000 chars per rich_text/URL.
Inputs: block_id (required), children (required), after, format.
notion_create_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), parent, discussion_id, format.
notion_create_databaseC
Create a database in Notion
Inputs: parent (required), properties (required), title, format.
notion_create_database_itemB
Create a new item (page) in a Notion database
Inputs: database_id (required), properties (required), format.
notion_create_pageA
Create a page as child of page or database. LIMITS: 100 blocks, 2 nesting levels, 2000 chars.
Inputs: parent (required), properties (required), children, format.
notion_delete_blockC
Delete a block in Notion
Inputs: block_id (required), format.
notion_list_all_usersA
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: start_cursor, page_size, format.
notion_query_databaseC
Query a database in Notion
Inputs: database_id (required), filter, sorts, start_cursor, +2 more.
notion_retrieve_blockB
Retrieve a block from Notion
Inputs: block_id (required), format.
notion_retrieve_block_childrenC
Retrieve the children of a block
Inputs: block_id (required), start_cursor, page_size, format.
notion_retrieve_bot_userB
Retrieve the bot user associated with the current token in Notion
Inputs: random_string (required), format.
notion_retrieve_commentsB
Retrieve a list of unresolved comments from a Notion page or block. Requires the integration to have 'read comment' capabilities.
Inputs: block_id (required), start_cursor, page_size, format.
notion_retrieve_databaseB
Retrieve a database in Notion
Inputs: database_id (required), format.
notion_retrieve_pageB
Retrieve a page from Notion
Inputs: page_id (required), format.
notion_retrieve_userA
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_searchB
Search pages or databases by title in Notion
Inputs: query, filter, sort, start_cursor, +2 more.
notion_update_blockA
Update the content of a block in Notion based on its type. The update replaces the entire value for a given field.
Inputs: block_id (required), block (required), format.
notion_update_databaseC
Update a database in Notion
Inputs: database_id (required), title, description, properties, +1 more.
notion_update_page_propertiesB
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 19 tools
Most tools have distinct purposes targeting specific Notion resources (blocks, databases, pages, users, comments), but some potential overlap exists between notion_create_page and notion_create_database_item (both create pages, though in different contexts) and between notion_retrieve_block and notion_retrieve_page (both retrieve content, but blocks vs. pages). The descriptions help clarify these distinctions.
All tool names follow a consistent verb_noun pattern with 'notion_' prefix (e.g., notion_create_page, notion_retrieve_database, notion_update_block). The verbs (append, create, delete, list, query, retrieve, search, update) are used predictably across resources, making the set highly readable and systematic.
19 tools is slightly high but reasonable for a Notion server covering blocks, databases, pages, users, and comments. It includes essential CRUD operations and utilities like search and listing, though it might be borderline heavy compared to simpler APIs. Each tool appears to serve a specific function without obvious redundancy.
The tool set provides comprehensive coverage of the Notion domain, including full CRUD for blocks, databases, pages, and comments, plus utilities like search, user management, and querying. There are no apparent gaps; agents can perform complete workflows from creation to deletion and retrieval across all major resource types.
Maintenance
Related MCP Connectors
Hosted Notion MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
MCP server for AI dialogue using various LLM models via AceDataCloud
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceA high-performance MCP server that integrates Notion into AI workflows, enabling interaction with Notion pages, databases, and comments through a standardized protocol.833 npm26Apache 2.0
- -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-
- 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,904 npm36Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server for Notion API with optimized token efficiency and full database property filtering, enabling AI assistants to manage pages, databases, and blocks.3220 npm1MIT