@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 pages - Supports both
NOTION_API_TOKENandNOTION_API_KEYenvironment variables - Enhanced error handling with detailed HTTP status code messages
Installation```bash
npx -y @suncreation/mcp-notion-server
## Quick Start
### 1. Create a Notion Integration
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_`)
### 2. Connect Integration to Pages
1. Open the Notion page you want to access
2. Click **"···"** (top right) → **"Connections"**
3. Add your integration
### 3. Configure Your MCP Client
#### 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
}
}
}
Environment Variables
| 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.
Available Tools
Pages
| Tool | Description |
|---|---|
notion_retrieve_page |
Get page information |
notion_update_page_properties |
Update page properties |
notion_create_page |
Create a new page (enhanced feature) |
Blocks
| Tool | Description |
|---|---|
notion_retrieve_block |
Get block information |
notion_retrieve_block_children |
Get child blocks |
notion_append_block_children |
Add blocks to a page/block |
notion_delete_block |
Delete a block |
Databases
| 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 |
Search & Users
| 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 |
Comments
| 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_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_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 install
Build
npm run build
Test
npm test
Watch mode
npm run watch
```
Changes from Original
This fork includes the following enhancements over @suekou/mcp-notion-server:
notion_create_pagetool - Create new pages under existing pages- Dual environment variable support - Both
NOTION_API_TOKENandNOTION_API_KEYwork - Enhanced 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
- Setup guides: English | Japanese
