https://github.com/makenotion/notion-mcp-server

Official Notion MCP Server
https://github.com/makenotion/notion-mcp-server

Last synced: 3 days ago
JSON representation

Official Notion MCP Server

• Host: GitHub
• URL: https://github.com/makenotion/notion-mcp-server
• Owner: makenotion
• License: mit
• Created: 2025-03-10T18:09:08.000Z (about 1 month ago)
• Default Branch: main
• Last Pushed: 2025-04-13T17:38:20.000Z (3 days ago)
• Last Synced: 2025-04-13T20:56:05.880Z (3 days ago)
• Language: TypeScript
• Homepage:
• Size: 961 KB
• Stars: 1,095
• Watchers: 9
• Forks: 38
• Open Issues: 7
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-mcp-servers - Notion - Notion official MCP server (Official Servers)

README

        
# Notion MCP Server

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

This project implements an [MCP server](https://spec.modelcontextprotocol.io/) for the [Notion API](https://developers.notion.com/reference/intro). 

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

### Installation

#### 1. Setting up Integration in Notion:

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)

While we limit the scope of Notion API's exposed (for example, you will not be able to delete databases via MCP), there is a non-zero risk to workspace data by exposing it to LLMs. Security-conscious users may want to further configure the Integration's _Capabilities_. 

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

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

#### 2. Adding MCP config to your 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`)

```javascript

{

  "mcpServers": {

    "notionApi": {

      "command": "npx",

      "args": ["-y", "@notionhq/notion-mcp-server"],

      "env": {

        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2022-06-28\" }"

      }

    }

  }

}

```

##### Using Docker:

You can also run the MCP server using Docker. First, build the Docker image:

```bash

docker-compose build

```

Then, add the following 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-notion-mcp-server"

      ]

    }

  }

}

```

Don't forget to replace `ntn_****` with your integration secret. Find it from your integration configuration tab:

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

#### 3. Connecting content to integration:

Ensure relevant pages and databases are connected to your integration.

To do this, you'll need to visit that page, and click on the 3 dots, and select "Connect to integration". 

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

### Examples

1. Using the following instruction

```

Comment "Hello MCP" on page "Getting started"

```

AI will correctly plan two API calls, `v1/search` and `v1/comments`, to achieve the task

2. Similarly, the following instruction will result in a new page named "Notion MCP" added to parent page "Development"

```

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

```

3. You may also reference content ID directly

```

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

```

### Development

Build

```

npm run build

```

Execute

```

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

```

Publish

```

npm publish --access public

```