notion-mcp-server

# Notion MCP Server

> [!NOTE]
>
> We've introduced **Notion MCP** (Beta), a remote MCP server with the following improvements:
> - **Easy Installation:** Simplified setup via standard OAuth. No more manual JSON or API token configuration.
> - **AI Agent Optimized:** Powerful tools specifically designed for AI agents, focusing on efficient token consumption.
>
> Learn more and try it out [here](https://notion.notion.site/Beta-Overview-Notion-MCP-206efdeead058060a59bf2c14202bd0a)

This project implements an [MCP (Model Context Protocol) server](https://spec.modelcontextprotocol.io/) for the [Notion API](https://developers.notion.com/reference/intro).  It allows AI agents to interact with your Notion workspace through a standardized protocol.

![notion-mcp-sm](https://github.com/user-attachments/assets/6c07003c-8455-4636-b298-d60ffdf46cd8)

![mcp-demo](https://github.com/user-attachments/assets/e3ff90a7-7801-48a9-b807-f7dd47f0d3d6)

## Getting Started

This guide will walk you through setting up the Notion MCP server and configuring your AI client to use it.

### Prerequisites

*   A Notion account.
*   An AI client that supports the Model Context Protocol (MCP). Examples include Cursor and Claude.
*   Node.js and npm (for npm installation) or Docker (for Docker installation).

## Installation

### 1. Notion Integration Setup

To allow the MCP server to access your Notion workspace, you need to create an internal integration:

1.  Go to [https://www.notion.so/profile/integrations](https://www.notion.so/profile/integrations) and create a new **internal** integration or select an existing one.

    ![Creating a Notion Integration token](docs/images/integrations-creation.png)

2.  **Security Considerations:** While the MCP server limits the scope of the Notion API exposed (e.g., database deletion is disabled), exposing workspace data to LLMs carries inherent risks.  Consider configuring the Integration's _Capabilities_ for enhanced security.

    For example, create a read-only integration token by granting only "Read content" access from the "Configuration" tab:

    ![Notion Integration Token Capabilities showing Read content checked](docs/images/integrations-capabilities.png)

### 2. Connecting Content to the Integration

Grant the integration access to specific pages and databases within your Notion workspace:

1.  Visit the **Access** tab in your internal integration settings. Click "Edit access" and select the pages you want the integration to access.

    ![Integration Access tab](docs/images/integration-access.png)

    ![Edit integration access](docs/images/page-access-edit.png)

2.  Alternatively, grant access on a per-page basis.  Navigate to the target page, click the three dots (•••), and select "Connect to integration."

    ![Adding Integration Token to Notion Connections](docs/images/connections.png)

### 3. Configuring Your AI Client

Configure your AI client (e.g., Cursor, Claude) to use the Notion MCP server.  This typically involves modifying a configuration file (e.g., `.cursor/mcp.json` or `claude_desktop_config.json`).

#### Option 1: Using npm

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

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

    *   Replace `ntn_****` with your actual Notion integration secret.

#### Option 2: Using Docker

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

##### Option 2.1: Using the Official Docker Hub Image

1.  Add the following configuration to your `.cursor/mcp.json` or `claude_desktop_config.json`:

    ```javascript
    {
      "mcpServers": {
        "notionApi": {
          "command": "docker",
          "args": [
            "run",
            "--rm",
            "-i",
            "-e", "OPENAPI_MCP_HEADERS",
            "mcp/notion"
          ],
          "env": {
            "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2022-06-28\"}"
          }
        }
      }
    }
    ```

    *   Replace `ntn_****` with your actual Notion integration secret.
    *   This approach uses the pre-built image from Docker Hub, simplifying setup.  It also correctly handles JSON escaping via environment variables.

##### Option 2.2: Building the Docker Image Locally

1.  Build the Docker image:

    ```bash
    docker-compose build
    ```

2.  Add the following configuration to your `.cursor/mcp.json` or `claude_desktop_config.json`:

    ```javascript
    {
      "mcpServers": {
        "notionApi": {
          "command": "docker",
          "args": [
            "run",
            "--rm",
            "-i",
            "-e",
            "OPENAPI_MCP_HEADERS={\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2022-06-28\"}",
            "notion-mcp-server"
          ]
        }
      }
    }
    ```

    *   Replace `ntn_****` with your actual Notion integration secret.

    *   This approach requires building the image locally, giving you more control over the environment.

3.  **Finding Your Integration Secret:**  Locate your integration secret in the "Configuration" tab of your integration settings in the Notion developer portal.

    ![Copying your Integration token from the Configuration tab in the developer portal](https://github.com/user-attachments/assets/67b44536-5333-49fa-809c-59581bf5370a)

#### Option 3: Installing via Smithery

[![smithery badge](https://smithery.ai/badge/@makenotion/notion-mcp-server)](https://smithery.ai/server/@makenotion/notion-mcp-server)

To automatically install the Notion API Server for Claude Desktop using [Smithery](https://smithery.ai/server/@makenotion/notion-mcp-server):

```bash
npx -y @smithery/cli install @makenotion/notion-mcp-server --client claude

Examples

Here are some example instructions you can give to your AI agent to interact with Notion through the MCP server:

1. Commenting on a Page:

   Comment "Hello MCP" on page "Getting started"

   This will trigger the AI to plan and execute two API calls: v1/search (to find the page) and v1/comments (to add the comment).
2. Adding a Page:

   Add a page titled "Notion MCP" to page "Development"

   This will create a new page named "Notion MCP" as a child of the page "Development."
3. Retrieving Page Content by ID:

   Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

   This will retrieve the content of the Notion page with the specified ID.

Development

For developers looking to contribute or modify the Notion MCP server:

Build

npm run build

Execute (Locally)

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

• Replace /path/to/local/notion-mcp-server with the actual path to your local development directory.

Publish

npm publish --access public