Notion MCP Server (Official)

🚀 Notion MCP Server

This project implements an MCP Server for the Notion API.

🚀 Quick Start

📦 Installation

1. Set up an integration in Notion:

Visit https://www.notion.so/profile/integrations and create a new Internal integration or select an existing one.

Although we limit the exposure scope of the Notion API (e.g., you cannot delete databases via MCP), there are still certain risks in exposing data to LLMs. Security-conscious users may want to further configure the capabilities of the integration.

For example, you can create a read-only integration token that only grants "Read content" access, which can be selected from the "Configuration" tab:

2. Add MCP configuration to the client:

Using npm:

Add the following to your .cursor/mcp.json or claude_desktop_config.json (MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2022-06-28\" }"
      }
    }
  }
}

Using Docker:

There are two ways to run the MCP server using Docker:

Method 1: Use the official Docker image:

Add the following to your docker-compose.yml to start the MCP server:

version: '3'
services:
  notion-mcp-server:
    image: ghcr.io/notionhq/notion-mcp-server:latest
    ports:
      - "19000:19000"

Then run:

docker-compose up --build

Method 2: Build and run locally:

Install the dependencies:

npm install @notionhq/notion-mcp-server --save-dev

Add a script to your package.json:

{
  "scripts": {
    "mcp-server": "npx -y --prefix . @notionhq/notion-mcp-server"
  }
}

Run:

npm run mcp-server

3. Connect content to the integration:

In Notion, navigate to the content (page or database) you want to connect, and then use the "Settings" menu in the sidebar to connect the content to the previously created integration.

💻 Usage Examples

Basic Usage

1. Add a comment:

post http://localhost:19000/comments
Content-Type: application/json

{
  "parent": "page_id",
  "content": "This is a test comment."
}

2. Get page content:

get http://localhost:19000/page_content?page_id=page_id

3. Search for content:

post http://localhost:19000/search
Content-Type: application/json

{
  "query": "Content to search for"
}

🔧 Technical Details

Build

npm run build

Run

npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server

Publish

npm publish --access public