Skip to main content
Glama
MCP Notion Server (@suncreation)

MCP Notion Server (@suncreation)

by SunCreation

@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

Related MCP server: Notion MCP Server

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

Available Tools

19 tools
notion_append_block_childrenA

Append children blocks to a parent block. LIMITS: Max 100 blocks, 2 nesting levels, 2000 chars per rich_text/URL.

Inputs: block_id (required), children (required), after, format.

notion_create_commentA

Create a comment in Notion. This requires the integration to have 'insert comment' capabilities. You can either specify a page parent or a discussion_id, but not both.

Inputs: rich_text (required), parent, discussion_id, format.

notion_create_databaseC

Create a database in Notion

Inputs: parent (required), properties (required), title, format.

notion_create_database_itemB

Create a new item (page) in a Notion database

Inputs: database_id (required), properties (required), format.

notion_create_pageA

Create a page as child of page or database. LIMITS: 100 blocks, 2 nesting levels, 2000 chars.

Inputs: parent (required), properties (required), children, format.

notion_delete_blockC

Delete a block in Notion

Inputs: block_id (required), format.

notion_list_all_usersA

List all users in the Notion workspace. Note: This function requires upgrading to the Notion Enterprise plan and using an Organization API key to avoid permission errors.

Inputs: start_cursor, page_size, format.

notion_query_databaseC

Query a database in Notion

Inputs: database_id (required), filter, sorts, start_cursor, +2 more.

notion_retrieve_blockB

Retrieve a block from Notion

Inputs: block_id (required), format.

notion_retrieve_block_childrenC

Retrieve the children of a block

Inputs: block_id (required), start_cursor, page_size, format.

notion_retrieve_bot_userB

Retrieve the bot user associated with the current token in Notion

Inputs: random_string (required), format.

notion_retrieve_commentsB

Retrieve a list of unresolved comments from a Notion page or block. Requires the integration to have 'read comment' capabilities.

Inputs: block_id (required), start_cursor, page_size, format.

notion_retrieve_databaseB

Retrieve a database in Notion

Inputs: database_id (required), format.

notion_retrieve_pageB

Retrieve a page from Notion

Inputs: page_id (required), format.

notion_retrieve_userA

Retrieve a specific user by user_id in Notion. Note: This function requires upgrading to the Notion Enterprise plan and using an Organization API key to avoid permission errors.

Inputs: user_id (required), format.

notion_update_blockA

Update the content of a block in Notion based on its type. The update replaces the entire value for a given field.

Inputs: block_id (required), block (required), format.

notion_update_databaseC

Update a database in Notion

Inputs: database_id (required), title, description, properties, +1 more.

notion_update_page_propertiesB

Update properties of a page or an item in a Notion database

Inputs: page_id (required), properties (required), format.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 19 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting specific Notion resources (blocks, databases, pages, users, comments), but some potential overlap exists between notion_create_page and notion_create_database_item (both create pages, though in different contexts) and between notion_retrieve_block and notion_retrieve_page (both retrieve content, but blocks vs. pages). The descriptions help clarify these distinctions.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with 'notion_' prefix (e.g., notion_create_page, notion_retrieve_database, notion_update_block). The verbs (append, create, delete, list, query, retrieve, search, update) are used predictably across resources, making the set highly readable and systematic.

    Tool Count4/5

    19 tools is slightly high but reasonable for a Notion server covering blocks, databases, pages, users, and comments. It includes essential CRUD operations and utilities like search and listing, though it might be borderline heavy compared to simpler APIs. Each tool appears to serve a specific function without obvious redundancy.

    Completeness5/5

    The tool set provides comprehensive coverage of the Notion domain, including full CRUD for blocks, databases, pages, and comments, plus utilities like search, user management, and querying. There are no apparent gaps; agents can perform complete workflows from creation to deletion and retrieval across all major resource types.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      An MCP server that enables natural language interaction with the Notion API, allowing users to search, comment, create pages, and access content within their Notion workspace.
      282,573 npm
      -
    • A
      license
      A
      quality
      A
      maintenance
      Markdown-first MCP server for Notion that provides 7 composite action-based tools consolidating 28+ REST API endpoints, enabling AI agents to efficiently manage pages, databases, blocks, and content with automatic pagination and bulk operations.
      10
      1,904 npm
      36
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server for Notion API with optimized token efficiency and full database property filtering, enabling AI assistants to manage pages, databases, and blocks.
      32
      20 npm
      1
      MIT