---
title: "Notion MCP Server: Official Setup for Claude and Cursor"
url: "https://mcpshelf.co/servers/notion"
description: "Notion's own MCP server lets an assistant search, read and update the pages and databases you share with it. Hosted and local setup, and tokens."
updated: "2026-10-27"
site: "MCP Shelf"
---

# Notion

> Notion's own server: search, read and update pages and databases.

Source: https://mcpshelf.co/servers/notion  
Markdown: https://mcpshelf.co/servers/notion.md  
Generated: 2026-11-22T17:16:26.517Z

## Facts

- **Name:** Notion
- **Tagline:** Notion's own server: search, read and update pages and databases.
- **Description:** The Notion MCP server is Notion's official MCP server that lets AI assistants search, read, create and update pages and databases in your Notion workspace, signing in with your Notion account.
- **Repository:** https://github.com/makenotion/notion-mcp-server
- **Package:** @notionhq/notion-mcp-server 2.5.2 (npm)
- **Install:** `claude mcp add --transport http notion https://mcp.notion.com/mcp`
- **Server URL:** https://mcp.notion.com/mcp
- **Transport:** stdio (local), or HTTP via the hosted server
- **Auth:** Needs `NOTION_TOKEN`
- **Tools exposed:** 24: `API-get-user`, `API-get-users`, `API-get-self`, `API-post-search`, `API-get-block-children`, `API-patch-block-children`, `API-retrieve-a-block`, `API-update-a-block`, `API-delete-a-block`, `API-retrieve-a-page`, `API-patch-page`, `API-post-page`, `API-retrieve-a-page-property`, `API-retrieve-a-comment`, `API-create-a-comment`, `API-query-data-source`, `API-retrieve-a-data-source`, `API-update-a-data-source`, `API-create-a-data-source`, `API-list-data-source-templates`, `API-retrieve-a-database`, `API-move-page`, `API-retrieve-page-markdown`, `API-update-page-markdown`
- **Category:** Knowledge and work apps (https://mcpshelf.co/categories/knowledge-and-work)
- **Stats:** 4.7K GitHub stars, 106.7K downloads a week, last commit 28 Oct 2026, 0 upvotes on MCP Shelf
- **Install check:** Started in our test
- **Listed:** 2026-10-26
- **Page updated:** 2026-10-27

## Full description

### What is Notion?

**The Notion MCP server is Notion's official MCP server that lets AI assistants search, read, create and update pages and databases in your Notion workspace, signing in with your Notion account.**

Notion runs this server at mcp.notion.com. The assistant can search your workspace, read pages, query databases and create or update content, with the access your own Notion account has, after you sign in with OAuth.

Notion also published an open source version that runs on your machine with an integration token. Notion no longer actively maintains it and now recommends the hosted server, but it still works for setups that need a token.

|  |  |
| --- | --- |
| Made by | Notion (makenotion) |
| GitHub | https://github.com/makenotion/notion-mcp-server |
| Licence | MIT |
| npm package | [@notionhq/notion-mcp-server](https://www.npmjs.com/package/@notionhq/notion-mcp-server) 2.5.2 (20 Sept 2026) |
| GitHub stars | 4.7K |
| Downloads | 106.7K a week |
| Last commit | 28 Oct 2026 |
| Tools | 24 |
| Runs on | Hosted or your computer |
| Install check | Started in our test |
| Category | [Knowledge and work apps](https://mcpshelf.co/categories/knowledge-and-work) |
| Works with | Claude Code, Cursor, Claude Desktop, VS Code, Codex, Windsurf |
| Setup checked | 27 Oct 2026 |
| Page updated | 27 Oct 2026 |

**Our check:** We ran this exact config on 26 Oct 2026: it started and answered with 24 tools.

#### Try asking Notion

- "Find my notes from last week’s planning meeting and summarise the decisions."
- "Add a task to the Roadmap database: "Ship onboarding emails", due Friday."
- "Create a page under Docs that explains our release process."

#### MCP Shelf take

> We started Notion on our own test machine on 26 Oct 2026 and it answered with 24 tools. 12 of the 24 only read; the other 12 can change things. Every tool comes with a useful description, all of them say whether they change things, and the tool list costs about 1,200 tokens of context before you ask a thing. It sits 3rd of 17 in its category on our shelf by GitHub stars (4.7K, with 106.7K downloads a week).

— MCP Shelf tests (numbers from our own runs), tested on 26 Oct 2026

### What tools does Notion have?

We listed 24 tools on 26 Oct 2026. 12 only read; the rest can change things or run commands.

| Tool | Kind | What it is for |
| --- | --- | --- |
| `API-get-user` | reads | Looks up one person or bot in the workspace by id. |
| `API-get-users` | reads | Lists the people and bots in the workspace. |
| `API-get-self` | reads | Shows which bot user the token belongs to, handy for checking the connection works. |
| `API-post-search` | changes | Finds pages and databases the integration can see by matching their titles. |
| `API-get-block-children` | reads | Lists the blocks nested inside a page or another block, one page of results at a time. |
| `API-patch-block-children` | changes | Adds new blocks to the end of a page, or after a block you pick. |
| `API-retrieve-a-block` | reads | Fetches a single block and its content. |
| `API-update-a-block` | changes | Edits the text or settings of an existing block. |
| `API-delete-a-block` | changes | Moves one block, such as a paragraph or to-do, to the trash. |
| `API-retrieve-a-page` | reads | Fetches a page's properties, such as its title, status and dates. |
| `API-patch-page` | changes | Changes a page's properties, icon or cover, or sends it to the trash. |
| `API-post-page` | changes | Creates a page, either under another page or as a new row in a database. |
| `API-retrieve-a-page-property` | reads | Reads one property in full, useful when a relation or rollup has many entries. |
| `API-retrieve-a-comment` | reads | Reads the comments left on a page or block. |
| `API-create-a-comment` | changes | Leaves a new comment on a page or adds a reply to an existing discussion. |
| `API-query-data-source` | changes | Pulls rows from a database using filters and sort order. |
| `API-retrieve-a-data-source` | reads | Returns a database's columns and settings so the agent knows its shape. |
| `API-update-a-data-source` | changes | Renames a database or changes its columns. |
| `API-create-a-data-source` | changes | Makes a new database table under a page, with the columns you describe. |
| `API-list-data-source-templates` | reads | Lists the page templates set up on a database. |
| `API-retrieve-a-database` | reads | Gets a database's details, including the ids of the data sources inside it. |
| `API-move-page` | changes | Moves a page under a different parent page or database. |
| `API-retrieve-page-markdown` | reads | Reads a whole page as Markdown, which costs far fewer tokens than block JSON. |
| `API-update-page-markdown` | changes | Rewrites a page, or swaps out parts of it, using Markdown. |

#### How clearly it describes its tools

24 of 24 tools have a description and 24 of 24 say whether they change things. The tool list takes at least ~1,200 tokens of context. Every tool says whether it only reads or can change things, so a client can ask before the risky ones.

### How do I install Notion?

#### Install steps from the Notion README

Copied from the project's [README on GitHub](https://github.com/makenotion/notion-mcp-server#readme) on 27 Oct 2026 under its MIT licence.

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

(image: Creating a Notion Integration token)

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:

(image: Notion Integration Token Capabilities showing Read content checked)

##### 2. Connecting content to integration

Ensure relevant pages and databases are connected to your integration.

To do this, visit the **Access** tab in your internal integration settings. Edit access and select the pages you'd like to use.

(image: Integration Access tab)

(image: Edit integration access)

Alternatively, you can grant page access individually. You'll need to visit the target page, and click on the 3 dots, and select "Connect to integration".

(image: Adding Integration Token to Notion Connections)

##### 3. Adding MCP config to your client

##### Using npm

##### Cursor & Claude

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

##### Option 1: Using NOTION_TOKEN (recommended)

```
{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}
```

##### Option 2: Using OPENAPI_MCP_HEADERS (for advanced use cases)

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

##### Zed

Add the following to your `settings.json`

```
{
  "context_servers": {
    "some-context-server": {
      "command": {
        "path": "npx",
        "args": ["-y", "@notionhq/notion-mcp-server"],
        "env": {
          "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
        }
      },
      "settings": {}
    }
  }
}
```

##### GitHub Copilot CLI

Use the Copilot CLI to interactively add the MCP server:

```
/mcp add
```

Alternatively, create or edit the configuration file `~/.copilot/mcp-config.json` and add:

```
{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}
```

For more information, see the [Copilot CLI documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli).

##### Using Docker

There are two options for running the MCP server with Docker:

##### Option 1: Using the official Docker Hub image

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

Using NOTION_TOKEN (recommended):

```
{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "NOTION_TOKEN",
        "mcp/notion"
      ],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}
```

Using OPENAPI_MCP_HEADERS (for advanced use cases):

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

This approach:

- Uses the official Docker Hub image
- Properly handles JSON escaping via environment variables
- Provides a more reliable configuration method

##### Option 2: Building the Docker image locally

You can also build and run the Docker image locally. First, build the Docker image:

```
docker compose build
```

Then, add the following to your `.cursor/mcp.json` or `claude_desktop_config.json`

Using NOTION_TOKEN (recommended):

```
{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "NOTION_TOKEN=ntn_****",
        "notion-mcp-server"
      ]
    }
  }
}
```

Using OPENAPI_MCP_HEADERS (for advanced use cases):

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

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

(image: Copying your Integration token from the Configuration tab in the developer portal)

#### What you need first

- A Notion account (the hosted server signs in with OAuth)
- For the local server only: an integration token shared with your pages, and Node.js 18 or newer

#### Claude Code

Where: Your terminal

```bash
claude mcp add --transport http notion https://mcp.notion.com/mcp
```

Then run /mcp inside Claude Code and sign in to Notion in the browser. Add --scope user to have it in every project.

#### Cursor

Where: ~/.cursor/mcp.json, or .cursor/mcp.json in a project

```json
{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}
```

Put it in .cursor/mcp.json for one project or ~/.cursor/mcp.json for all, then enable Notion in Cursor's MCP settings and finish the sign-in.

#### Claude Desktop

Where: Settings → Connectors

```
https://mcp.notion.com/mcp
```

Notion is in Claude's connector directory, so you can add it there, or add this URL as a custom connector. Either way you sign in with your Notion account.

#### VS Code

Where: .vscode/mcp.json in your project

```json
{
  "servers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}
```

Save as .vscode/mcp.json, run MCP: List Servers from the Command Palette, start Notion and sign in when asked.

#### Codex

Where: ~/.codex/config.toml, shared by the Codex CLI, IDE extension and ChatGPT desktop app

```
[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"
```

Or run: `codex mcp add notion --url https://mcp.notion.com/mcp`, then `codex mcp login notion` if it asks you to sign in.

#### Windsurf

Where: ~/.codeium/windsurf/mcp_config.json

```json
{
  "mcpServers": {
    "notion": {
      "serverUrl": "https://mcp.notion.com/mcp"
    }
  }
}
```

#### ChatGPT

Where: chatgpt.com/plugins

Notion has a ready-made app in ChatGPT's directory, so search for Notion there and sign in rather than adding a server by hand.

Replace ntn_**** with your integration token and share the relevant pages with that integration.

#### Remote option

The hosted server signs in with your Notion account instead of a token.

```
https://mcp.notion.com/mcp
```

Checked against the project's own install docs on 27 Oct 2026: https://developers.notion.com/docs/get-started-with-mcp, https://github.com/makenotion/notion-mcp-server#readme

### How do I configure Notion?

| Setting | Kind | Required | What it does |
| --- | --- | --- | --- |
| `NOTION_TOKEN` | env | yes | Your internal integration secret from Notion's integrations page. The simplest way to sign in. Example: `ntn_xxxxxxxx` |
| `OPENAPI_MCP_HEADERS` | env | no | An alternative to NOTION_TOKEN: a JSON string of raw request headers, for when you need to pin the Notion-Version yourself. Example: `{"Authorization": "Bearer ntn_xxxx", "Notion-Version": "2025-09-03"}` |
| `--transport` | flag | no | Choose stdio (the default) or http to run it as a local web server. Example: `--transport http` |
| `--port` | flag | no | Port for the HTTP mode. Defaults to 3000. Example: `--port 8080` |
| `--auth-token` | flag | no | Bearer token clients must send in HTTP mode. One is generated for you if you leave it out. Example: `--auth-token your-secret` |
| `AUTH_TOKEN` | env | no | The same bearer token as --auth-token, set through the environment. |
| `--enable-token-passthrough` | flag | no | Lets each HTTP client send its own Notion token in a Notion-Token header, so one server can serve several integrations. Also settable with ENABLE_TOKEN_PASSTHROUGH=true. |
| `--unsafe-disable-auth` | flag | no | Turns off the HTTP bearer check. Only for an isolated network. |

### What can Notion read and change?

**It can read**

- Pages and databases you have shared with the integration, and nothing else
- Comments and the list of workspace members

**It can change**

- Creates, edits, moves and trashes pages and blocks
- Adds database rows and changes database columns
- Posts comments

**Safer setup:** In the integration's Configuration tab, tick only "Read content". The agent can then read the pages you share but cannot write anything.

### Good for

- Drafting docs straight into Notion
- Answering questions from your wiki
- Updating task databases from a chat

### Notion not working? Common fixes

**Search returns nothing, or a page gives a 404**
Notion hides everything from an integration until you share it. Add the pages in the integration's Access tab, or use Connect to integration from the page's ••• menu.

**Old prompts call post-database-query and fail**
Version 2 swapped database tools for data source ones. Use query-data-source with a data_source_id instead.

**403 from the Markdown tools**
The integration needs read content (and update content for edits) switched on in its capabilities.

**The JSON headers break in the Docker config**
Use NOTION_TOKEN instead of OPENAPI_MCP_HEADERS. It needs no escaping.

### What are the alternatives to Notion?

| Server | What it does | Tools | Runs on | Licence | Stars |
| --- | --- | --- | --- | --- | --- |
| [Notion](https://mcpshelf.co/servers/notion) | Notion's own server: search, read and update pages and databases. | 24 | Hosted or your computer | MIT | 4.7K |
| [MCP Atlassian (Jira and Confluence)](https://mcpshelf.co/servers/atlassian) | Jira issues and Confluence pages, Cloud or self-hosted. | 98 | Your computer | MIT | 6.1K |
| [Basic Memory](https://mcpshelf.co/servers/basic-memory) | Long-term memory as plain Markdown files you own. | 27 | Your computer | AGPL-3.0-or-later | 4.4K |
| [LinkedIn MCP Server](https://mcpshelf.co/servers/linkedin) | Read LinkedIn profiles, companies and job posts with your own login. | 20 | Your computer | Apache-2.0 | 4K |
| [arXiv MCP Server](https://mcpshelf.co/servers/arxiv) | Search arXiv, download papers and read them in full. | 19 | Your computer | Apache-2.0 | 3.2K |
| [TradingView MCP](https://mcpshelf.co/servers/tradingview) | Prices, indicators, screeners and backtests for stocks, crypto and forex, no account needed. | 37 | Your computer or hosted | MIT | 5.2K |

### Notion FAQ

#### How do I add the Notion MCP server to Claude Code?

Run claude mcp add --transport http notion https://mcp.notion.com/mcp, then type /mcp in Claude Code and sign in to Notion in your browser. No integration token is needed for the hosted server.

#### How do I connect Notion MCP to Cursor?

Add a notion entry with the URL https://mcp.notion.com/mcp to .cursor/mcp.json or ~/.cursor/mcp.json, enable it in Cursor's MCP settings and complete the Notion sign-in that opens.

#### Should I use the hosted Notion MCP or the open source one?

Notion recommends the hosted server at mcp.notion.com, which signs in with OAuth and is the one it maintains. The open source notion-mcp-server is no longer actively maintained; use it only if you need an integration token or must run it yourself.

#### Can I use Notion MCP without signing in through a browser?

On Business and Enterprise plans a workspace owner can create an MCP token and send it as a bearer token. Otherwise, the local open source server takes an internal integration token instead of OAuth.

#### Is the Notion MCP server free?

Yes. The hosted server comes with your Notion account and the open source server is MIT licensed. What the assistant can do still depends on your Notion plan and permissions.

#### Is Notion MCP safe to connect?

It acts with your Notion access, so it can edit what you can edit. With the local server you can limit it to the pages you share with the integration and tick only Read content. There is no tool to delete a database.

#### Why can't the local Notion MCP server find my pages?

An internal integration only sees pages shared with it. Open the integration's Access tab, or use Connect to integration on a page, and share a top-level page so everything beneath it comes along.

#### Does Notion MCP work with ChatGPT?

Yes. Notion is available as a ready-made app in ChatGPT, so you sign in to Notion from ChatGPT's app directory. Codex, OpenAI's coding agent, can use the hosted URL directly.

#### Can I use Notion in VS Code?

Yes, through GitHub Copilot. In .vscode/mcp.json, add a server named notion with type http and the URL https://mcp.notion.com/mcp. Save as .vscode/mcp.json, run MCP: List Servers from the Command Palette, start Notion and sign in when asked.

#### Does Notion work with Codex?

Yes. Run codex mcp add notion --url https://mcp.notion.com/mcp in a terminal, or add an [mcp_servers.notion] table to ~/.codex/config.toml, which the Codex CLI and IDE extension share. Then codex mcp login notion if it asks you to sign in.

Full docs on GitHub: https://github.com/makenotion/notion-mcp-server

## Notes for agents

Fetch these instead of parsing the HTML page:

- llms.txt: https://mcpshelf.co/llms.txt
- llms-full.txt: https://mcpshelf.co/llms-full.txt
- ai.txt: https://mcpshelf.co/ai.txt
- Full catalog (.md): https://mcpshelf.co/catalog.md
- API spec: https://mcpshelf.co/openapi.json
- MCP server: https://mcpshelf.co/mcp
- MCP manifest: https://mcpshelf.co/.well-known/mcp.json
- Developer docs: https://mcpshelf.co/developers

MCP endpoint (Streamable HTTP, no key): https://mcpshelf.co/mcp. REST API: https://mcpshelf.co/api/v1.

