@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
- 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

Installation

``bash
npx -y @suncreation/mcp-notion-server
`

Quick Start

$3

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_)

$3

1. Open the Notion page you want to access
2. Click "···" (top right) → "Connections"
3. Add your integration

$3

#### 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

$3


| Tool | Description |
|------|-------------|
| notion_retrieve_page | 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_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:

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 needed

License

MIT License - see LICENSE file.

Credits

- Original project: @suekou/mcp-notion-server
- Setup guides: English | Japanese