@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

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

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

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