Notion MCP Server

A Model Context Protocol server for Notion API integration, providing tools to create, retrieve, and update Notion pages.

Features

• Create Page: Create new pages in databases or as child pages

• Retrieve Page: Get page properties and metadata

• Update Page: Modify page properties, icons, covers, and archive status

• Retrieve Page Property: Get detailed property information with pagination support

Related MCP server: Notion MCP Server

Installation

cd backend/notion-mcp
npm install

Configuration

Create a .env file with your Notion API key:

NOTION_API_KEY=your_notion_integration_token_here
NOTION_VERSION=2022-06-28
PORT=3003

Getting a Notion API Key

1. Go to Notion Developers

2. Create a new integration

3. Copy the "Internal Integration Token"

4. Share your databases/pages with the integration

Usage

STDIO Transport (Development)

npm run dev:stdio

HTTP Transport (Production)

npm run dev:http
# or
npm start

Available Tools

notion_create_page

Creates a new page in Notion.

Parameters:

• parent (required): Parent page or database ID

• properties (required): Page properties matching parent schema

• children (optional): Page content as block objects

• icon (optional): Page icon (emoji or external URL)

• cover (optional): Page cover image

Example:

{
  "parent": {
    "type": "database_id",
    "database_id": "d9824bdc-8445-4327-be8b-5b47500af6ce"
  },
  "properties": {
    "Name": {
      "title": [{"text": {"content": "New Page"}}]
    }
  },
  "icon": {
    "type": "emoji",
    "emoji": "📝"
  }
}

notion_retrieve_page

Retrieves a Notion page by ID.

Parameters:

• page_id (required): The page ID to retrieve

• filter_properties (optional): Specific property IDs to return

notion_update_page

Updates page properties and metadata.

Parameters:

• page_id (required): The page ID to update

• properties (optional): Properties to update

• in_trash (optional): Archive/restore the page

• icon (optional): Update page icon

• cover (optional): Update page cover

notion_retrieve_page_property

Retrieves detailed property information with pagination.

Parameters:

• page_id (required): The page ID

• property_id (required): The property ID

• page_size (optional): Number of items per page (max 100)

• start_cursor (optional): Pagination cursor

Building

npm run build

Development

npm run watch  # Watch mode for TypeScript compilation

Client Configuration

For HTTP transport, add to your MCP client config:

{
  "mcpServers": {
    "notion": {
      "url": "http://localhost:3003/mcp"
    }
  }
}

For STDIO transport:

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

Health Check

When running HTTP transport:

curl http://localhost:3003/health

Error Handling

The server provides detailed error messages for:

• Missing API keys

• Invalid page/database IDs

• Permission errors

• Malformed requests

• Notion API rate limits

License

MIT