MCP server for interacting with Notion API - forked and enhanced
npm install @suncreation/mcp-notion-serverMCP 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.
- 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 pages
- Recursive block fetching - Fetch nested blocks (toggles, tables, etc.) in a single call
- Supports both NOTION_API_TOKEN and NOTION_API_KEY environment variables
- Enhanced error handling with detailed HTTP status code messages
``bash`
npx -y @suncreation/mcp-notion-server
1. Visit the Notion Integrations page
2. Click "New Integration"
3. Name your integration and select permissions:
- ✅ Read content
- ✅ Update content
- ✅ Insert content
4. Copy the "Internal Integration Token" (starts with ntn_ or secret_)
1. Open the Notion page you want to access
2. Click "···" (top right) → "Connections"
3. Add your integration
#### OpenCode
Add to ~/.config/opencode/opencode.json:
`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:
`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:
`json`
{
"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
}
}
}
| Variable | Required | Description |
|----------|----------|-------------|
| NOTION_API_TOKEN | Yes* | Your Notion API integration token |NOTION_API_KEY
| | Yes* | Alternative name for the token (either works) |NOTION_MARKDOWN_CONVERSION
| | No | Set to "true" for Markdown output (reduces tokens) |
*One of NOTION_API_TOKEN or NOTION_API_KEY is required.
| Get page information |
| notion_update_page_properties | Update page properties |
| notion_create_page | Create a new page (enhanced feature) |$3
| Tool | Description |
|------|-------------|
| notion_retrieve_block | Get block information |
| notion_retrieve_block_children | Get child blocks (supports recursive option) |
| notion_append_block_children | Add blocks to a page/block |
| notion_delete_block | Delete a block |#### Recursive Block Fetching
notion_retrieve_block_children supports fetching nested blocks in a single call:`json
{
"block_id": "page-or-block-id",
"recursive": true,
"max_depth": 5
}
`-
recursive: true - Fetches all nested blocks (toggles, callouts, columns, etc.)
- max_depth - Maximum nesting depth (default: 5)
- Note: child_page and child_database are NOT followed (they are separate pages)$3
| Tool | Description |
|------|-------------|
| notion_create_database | Create a new database |
| notion_query_database | Query database entries |
| notion_retrieve_database | Get database schema |
| notion_update_database | Update database properties |
| notion_create_database_item | Add item to database |$3
| Tool | Description |
|------|-------------|
| notion_search | Search pages/databases by title |
| notion_list_all_users | List workspace users (Enterprise) |
| notion_retrieve_user | Get user details (Enterprise) |
| notion_retrieve_bot_user | Get bot user info |$3
| Tool | Description |
|------|-------------|
| notion_create_comment | Add a comment |
| notion_retrieve_comments | Get comments on a page/block |Command Line Options
`bash
Enable only specific tools
node build/index.js --enabledTools=notion_retrieve_page,notion_query_databaseRead-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_search
`Markdown Conversion
Enable Markdown conversion for reduced token usage:
`json
{
"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
`bash
Clone and install
git clone https://github.com/SunCreation/mcp-notion-server.git
cd mcp-notion-server
npm installBuild
npm run buildTest
npm testWatch mode
npm run watch
`Changes from Original
This fork includes the following enhancements over @suekou/mcp-notion-server:
1.
notion_create_page tool - Create new pages under existing pages
2. Recursive block fetching - recursive option for notion_retrieve_block_children
3. Dual environment variable support - Both NOTION_API_TOKEN and NOTION_API_KEY work
4. Enhanced error handling - Detailed HTTP status code messages for easier debugging
5. setApiVersion()` method - Dynamically change API version if neededMIT License - see LICENSE file.
- Original project: @suekou/mcp-notion-server
- Setup guides: English | Japanese