@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

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:

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

1. notion_create_page tool - Create new pages under existing pages
2. Dual environment variable support - Both NOTION_API_TOKEN and NOTION_API_KEY work
3. Enhanced error handling - Detailed HTTP status code messages for easier debugging
4. 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