@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_TOKEN and NOTION_API_KEY environment variables
Enhanced error handling with detailed HTTP status code messages

Installation

npx -y @suncreation/mcp-notion-server

Quick 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_ or secret_)

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

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

{
  "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 watch

Changes from Original

This fork includes the following enhancements over @suekou/mcp-notion-server:

notion_create_page tool - Create new pages under existing pages
Dual environment variable support - Both NOTION_API_TOKEN and NOTION_API_KEY work
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

MCP Notion Server (@suncreation)