Notion MCP Server
Notion's own server: search, read and update pages and databases.
- Started in our test
- ★ 4.7K GitHub stars
- 106.7K downloads a week
- Last commit 28 Oct 2026
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.
- Tools
- 24
- Runs on
- Hosted or your computer
- Licence
- MIT
- GitHub stars
- 4.7K
Good for
- Drafting docs straight into Notion
- Answering questions from your wiki
- Updating task databases from a chat
You'll need
- 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
Started in our testWe ran this exact config on 26 Oct 2026: it started and answered with 24 tools.
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 16 in its category on our shelf by GitHub stars (4.7K, with 106.7K downloads a week).
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.
Notion in more detail
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)
- Latest version
- 2.5.2 (20 Sept 2026)
- npm package
- @notionhq/notion-mcp-server
- Downloads
- 106.7K a week
- Last commit
- 28 Oct 2026
- Setup checked
- 27 Oct 2026
- Page updated
- 27 Oct 2026
What's in the pod
What tools does Notion have?
We found 24 tools when we started it on 26 Oct 2026. 12 only read. The rest can change things, so keep your app's "ask before each tool call" setting on for them.
Changes things12 tools · Can create, edit, send or delete.
| Tool | What it is for |
|---|---|
API-create-a-comment | Leaves a new comment on a page or adds a reply to an existing discussion. |
API-create-a-data-source | Makes a new database table under a page, with the columns you describe. |
API-delete-a-block | Moves one block, such as a paragraph or to-do, to the trash. |
API-move-page | Moves a page under a different parent page or database. |
API-patch-block-children | Adds new blocks to the end of a page, or after a block you pick. |
API-patch-page | Changes a page's properties, icon or cover, or sends it to the trash. |
API-post-page | Creates a page, either under another page or as a new row in a database. |
API-post-search | Finds pages and databases the integration can see by matching their titles. |
API-query-data-source | Pulls rows from a database using filters and sort order. |
API-update-a-block | Edits the text or settings of an existing block. |
API-update-a-data-source | Renames a database or changes its columns. |
API-update-page-markdown | Rewrites a page, or swaps out parts of it, using Markdown. |
Only reads12 tools · Looks things up and changes nothing.
| Tool | What it is for |
|---|---|
API-get-block-children | Lists the blocks nested inside a page or another block, one page of results at a time. |
API-get-self | Shows which bot user the token belongs to, handy for checking the connection works. |
API-get-user | Looks up one person or bot in the workspace by id. |
API-get-users | Lists the people and bots in the workspace. |
API-list-data-source-templates | Lists the page templates set up on a database. |
API-retrieve-a-block | Fetches a single block and its content. |
API-retrieve-a-comment | Reads the comments left on a page or block. |
API-retrieve-a-data-source | Returns a database's columns and settings so the agent knows its shape. |
API-retrieve-a-database | Gets a database's details, including the ids of the data sources inside it. |
API-retrieve-a-page | Fetches a page's properties, such as its title, status and dates. |
API-retrieve-a-page-property | Reads one property in full, useful when a relation or rollup has many entries. |
API-retrieve-page-markdown | Reads a whole page as Markdown, which costs far fewer tokens than block JSON. |
Grouped and described by us. The README on GitHub lists the inputs each tool takes.
How clearly it describes its tools to your assistant
- Tools with a description
- 24 of 24
- Say if they change things
- 24 of 24
- Context it takes, at least
- ~1,200 tokens
Every tool says whether it only reads or can change things, so a client can ask before the risky ones.
From the tool list it sent us. The token figure counts names, descriptions and input names; the full schemas your client loads add more.
How do I install Notion?
Install steps from the Notion README
The project's own instructions, copied from its README on GitHub on 27 Oct 2026 under its MIT licence. They are the source of truth; the ready-made configs further down are built from them. The rest of the README is in the README tab.
Installation
1. Setting up integration in Notion
Go to https://www.notion.so/profile/integrations and create a new internal integration or select an existing one.

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:

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.


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

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.
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:
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
Add Notion to your app
Pick your app for a ready-to-paste snippet and where it goes, built from the steps above.
Where it goes: Your terminal
claude mcp add --transport http notion https://mcp.notion.com/mcpThen run /mcp inside Claude Code and sign in to Notion in the browser. Add --scope user to have it in every project.
Where it goes: ~/.cursor/mcp.json, or .cursor/mcp.json in a project
{
"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.
Where it goes: Settings → Connectors
https://mcp.notion.com/mcpNotion 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.
Where it goes: .vscode/mcp.json in your project
{
"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.
Where it goes: ~/.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.
Where it goes: ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"notion": {
"serverUrl": "https://mcp.notion.com/mcp"
}
}
}Where it goes: 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/mcpChecked against the project's own install docs on 27 Oct 2026: developers.notion.com/docs/get-started-with-mcp, makenotion/notion-mcp-server README.
Did this work for you?
Projects change their install steps often. If Notion did not install, or something here no longer matches the project, tell us and we will check it against the README and fix the page.
New to this? See the setup guides for Claude Code, Cursor, Claude Desktop, VS Code, Codex and ChatGPT. If it will not start, test it in MCP Inspector and look up the error in Fixing MCP server errors.
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.
How do I configure Notion?
Names are exactly as the project spells them. Required ones are marked.
| Setting | What it does |
|---|---|
NOTION_TOKENEnvironment variable · required | Your internal integration secret from Notion's integrations page. The simplest way to sign in.ntn_xxxxxxxx |
OPENAPI_MCP_HEADERSEnvironment variable | An alternative to NOTION_TOKEN: a JSON string of raw request headers, for when you need to pin the Notion-Version yourself.{"Authorization": "Bearer ntn_xxxx", "Notion-Version": "2025-09-03"} |
--transportCommand line flag | Choose stdio (the default) or http to run it as a local web server.--transport http |
--portCommand line flag | Port for the HTTP mode. Defaults to 3000.--port 8080 |
--auth-tokenCommand line flag | Bearer token clients must send in HTTP mode. One is generated for you if you leave it out.--auth-token your-secret |
AUTH_TOKENEnvironment variable | The same bearer token as --auth-token, set through the environment. |
--enable-token-passthroughCommand line flag | 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-authCommand line flag | Turns off the HTTP bearer check. Only for an isolated network. |
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.
Notion README
This is the project's own README from makenotion/notion-mcp-server, written by Notion (makenotion), and shared under its MIT licence. We copied it on 27 Oct 2026, so the version on GitHub may be newer.
Notion MCP Server
Note:
For the best experience, use Remote Notion MCP, our official hosted MCP server. This repository is a separate, self-hosted MCP server implementation that is no longer actively maintained or supported. Please use Remote Notion MCP instead. It is purpose-built to give AI agents faster results using far fewer tokens.
Remote Notion MCP can search your workspace and connected apps semantically, read and edit pages in Markdown, and return only the most relevant context. That means less time waiting, less context-window usage, and lower token costs. It also uses OAuth and automatically respects each user's existing Notion permissions—without API tokens, JSON configuration, manual page sharing, or a local server to maintain.
Feature Remote Notion MCP This project (local) Fast, hosted experience ✅ Runs and updates locally Token-efficient responses ✅ Limited Powerful tools tailored for AI agents ✅ Basic API-derived tools Semantic search across your Notion workspace ✅ Keyword search only AI Connector search across connected apps ✅ Not available Markdown-native page reading and editing ✅ Limited to two page-content tools Seamless OAuth setup ✅ Manual token and JSON configuration Respects each user's existing Notion permissions ✅ Manual integration permissions and page sharing Active support and ongoing improvements ✅ Not actively supported Learn more and get started in the Remote Notion MCP documentation.
We are prioritizing, and only providing active support for, Remote Notion MCP. As a result:
- We may sunset this local MCP server repository in the future.
- Issues and pull requests here are not actively monitored.
- Please do not file issues relating to the remote MCP here; instead, contact Notion support.
This project implements an MCP server for the Notion API.
⚠️ Version 2.0.0 breaking changes
Version 2.0.0 migrates to the Notion API 2025-09-03 which introduces data sources as the primary abstraction for databases.
What changed
Removed tools (3):
post-database-query- replaced byquery-data-sourceupdate-a-database- replaced byupdate-a-data-sourcecreate-a-database- replaced bycreate-a-data-source
New tools (7):
query-data-source- Query a data source (database) with filters and sortsretrieve-a-data-source- Get metadata and schema for a data sourceupdate-a-data-source- Update data source propertiescreate-a-data-source- Create a new data sourcelist-data-source-templates- List available templates in a data sourcemove-page- Move a page to a different parent locationretrieve-a-database- Get database metadata including its data source IDs
Parameter changes:
- All database operations now use
data_source_idinstead ofdatabase_id - Search filter values changed from
["page", "database"]to["page", "data_source"] - Page creation now supports both
page_idanddatabase_idparents (for data sources)
Do I need to migrate?
No code changes required. MCP tools are discovered automatically when the server starts. When you upgrade to v2.0.0, AI clients will automatically see the new tool names and parameters. The old database tools are no longer available.
If you have hardcoded tool names or prompts that reference the old database tools, update them to use the new data source tools:
| Old Tool (v1.x) | New Tool (v2.0) | Parameter Change |
|---|---|---|
post-database-query |
query-data-source |
database_id → data_source_id |
update-a-database |
update-a-data-source |
database_id → data_source_id |
create-a-database |
create-a-data-source |
No change (uses parent.page_id) |
Note:
retrieve-a-databaseis still available and returns database metadata including the list of data source IDs. Useretrieve-a-data-sourceto get the schema and properties of a specific data source.
Total tools now: 22 (was 19 in v1.x)
Page content as Markdown
The server exposes two tools for working with page content as enhanced Markdown instead of block JSON, which is significantly more token-efficient for AI agents:
retrieve-page-markdown— Read a page's full content as Markdown (GET /v1/pages/{page_id}/markdown). Passinclude_transcript: trueto inline meeting-note transcripts.update-page-markdown— Edit a page's content with Markdown (PATCH /v1/pages/{page_id}/markdown). Preferreplace_contentto overwrite the whole page, orupdate_contentfor targeted find-and-replace edits.
These endpoints require Notion API version 2026-03-11. The server now sources the Notion-Version header per operation from the OpenAPI spec, so these tools use 2026-03-11 while the rest of the API continues to use 2025-09-03 — no configuration needed. If you set Notion-Version yourself via OPENAPI_MCP_HEADERS, your value takes precedence for every tool.
Installation
1. Setting up integration in Notion
Go to https://www.notion.so/profile/integrations and create a new internal integration or select an existing one.

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:

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.


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

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.
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:
Transport options
The Notion MCP Server supports two transport modes:
STDIO transport (default)
The default transport mode uses standard input/output for communication. This is the standard MCP transport used by most clients like Claude Desktop.
# Run with default stdio transport
npx @notionhq/notion-mcp-server
# Or explicitly specify stdio
npx @notionhq/notion-mcp-server --transport stdio
Streamable HTTP transport
For web-based applications or clients that prefer HTTP communication, you can use the Streamable HTTP transport:
# Run with Streamable HTTP transport on port 3000 (default)
npx @notionhq/notion-mcp-server --transport http
# Run on a custom port
npx @notionhq/notion-mcp-server --transport http --port 8080
# Bind to a different host. The default is 127.0.0.1.
npx @notionhq/notion-mcp-server --transport http --host 0.0.0.0
# Run with a custom authentication token
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"
When using Streamable HTTP transport, the server will be available at http://127.0.0.1:<port>/mcp by default.
Authentication
The Streamable HTTP transport requires bearer token authentication for security. You have three options:
Option 1: Auto-generated token (only for development)
npx @notionhq/notion-mcp-server --transport http
The server will generate a secure random token and write it to a file with restricted permissions:
Generated auth token written to: /tmp/.notion-mcp-auth-token-12345
Option 2: Custom token via command line (recommended for production)
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"
Option 3: Custom token via environment variable (recommended for production)
AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http
The command line argument --auth-token takes precedence over the AUTH_TOKEN environment variable if both are provided.
Unsafe option: disable HTTP authentication
You can disable bearer token authentication only with the explicit unsafe flag:
npx @notionhq/notion-mcp-server --transport http --unsafe-disable-auth
WARNING: --unsafe-disable-auth is unsafe. The server may be reachable to pages you visit via DNS rebinding. Only use it on an isolated network.
When authentication is disabled, the server enables DNS rebinding protection by checking the Host and Origin headers against the configured local host and loopback hosts. The previous --disable-auth flag is still accepted as a deprecated alias, but it will print a warning.
Making HTTP requests
All requests to the Streamable HTTP transport must include the bearer token in the Authorization header:
# Example request
curl -H "Authorization: Bearer your-token-here" \
-H "Content-Type: application/json" \
-H "mcp-session-id: your-session-id" \
-d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
http://localhost:3000/mcp
Note: Make sure to set either the NOTION_TOKEN environment variable (recommended) or the OPENAPI_MCP_HEADERS environment variable with your Notion integration token when using either transport mode.
Serving multiple integrations (per-request token passthrough)
By default the server authenticates to Notion with a single token baked in at startup, which locks one deployment to one Notion integration. To let a single deployment serve multiple integrations, enable token passthrough so each client supplies its own Notion integration token per connection:
# Enable per-request Notion tokens (flag or ENABLE_TOKEN_PASSTHROUGH=true)
npx @notionhq/notion-mcp-server --transport http --enable-token-passthrough
Clients then send their Notion token on the initialize request using the
dedicated Notion-Token header:
curl -H "Authorization: Bearer <server-auth-token>" \
-H "Notion-Token: ntn_****" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
http://localhost:3000/mcp
How the token is resolved for each connection, in order:
- The
Notion-Tokenheader (preferred — unambiguous, and works alongside the server's ownAuthorizationgateway auth). If present it must be a valid Notion token, otherwise the request is rejected with401. Authorization: Bearer ntn_****— only when the server's own bearer auth is turned off (--unsafe-disable-auth), so the header is free to carry the Notion token directly.- Otherwise the startup env token (
NOTION_TOKEN/OPENAPI_MCP_HEADERS), if set, so passthrough and a default integration can coexist on one deployment.
Notes:
- Only values with a Notion token prefix (
ntn_, legacysecret_) are treated as Notion tokens, so the server's gateway secret and a tenant's Notion token never collide. - Each token is bound to its MCP session; tokens are never logged (only a redacted prefix is emitted).
- This is a deliberate token-passthrough setup. Always deploy it over TLS, and
prefer keeping the server's own bearer auth (
--auth-token) enabled as a gateway in front of multi-tenant traffic.
Examples
- 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
- 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"
- You may also reference content ID directly
Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2
Development
Build & test
npm run build
npm test
Execute
npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server
Testing changes locally in Cursor:
- Run
npm linkcommand from repository root to create a machine-global symlink to thenotion-mcp-serverpackage. - Merge the configuration snippet below into Cursor's
mcp.json(or other MCP client you want to test with). - (Cleanup) run
npm unlinkfrom repository root.
{
"mcpServers": {
"notion-local-package": {
"command": "notion-mcp-server",
"env": {
"NOTION_TOKEN": "ntn_..."
}
}
}
}
Publish
npm login
npm publish --access public
Two peas, one chat
Chat with AI about Notion
Opens a chat primed with Notion’s README and setup docs from this page, or add it in Cursor to use its tools.
The Cursor button opens Cursor and asks before it adds the server. Fill in any keys it needs in Cursor’s MCP settings.
Peas in a pod
What are the alternatives to Notion?
How Notion lines up against its neighbours on the shelf. See every knowledge and work apps server.
NotionThis pea
Notion's own server: search, read and update pages and databases.
- Tools
- 24
- Runs on
- Hosted or your computer
- Licence
- MIT
- Stars
- 4.7K

MCP Atlassian (Jira and Confluence)
Jira issues and Confluence pages, Cloud or self-hosted.
- Tools
- 98
- Runs on
- Your computer
- Licence
- MIT
- Stars
- 6.1K

Long-term memory as plain Markdown files you own.
- Tools
- 27
- Runs on
- Your computer
- Licence
- AGPL-3.0-or-later
- Stars
- 4.4K

Read LinkedIn profiles, companies and job posts with your own login.
- Tools
- 20
- Runs on
- Your computer
- Licence
- Apache-2.0
- Stars
- 4K

Search arXiv, download papers and read them in full.
- Tools
- 19
- Runs on
- Your computer
- Licence
- Apache-2.0
- Stars
- 3.2K

Prices, indicators, screeners and backtests for stocks, crypto and forex, no account needed.
- Tools
- 37
- Runs on
- Your computer or hosted
- Licence
- MIT
- Stars
- 5.2K
Something wrong on this page? Tell us.
For bots & AI agents
Machine-readable versions of Notion and MCP Shelf. Fetch these instead of parsing this page.
This listing (.md)llms.txtllms-full.txtai.txtFull catalog (.md)API specMCP serverMCP manifestDeveloper docs