Skip to content
MCP Shelf

Notion MCP Server

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

View on GitHub
  • 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).
MCP Shelf tests: numbers from our own runs, not the README · tested on 26 Oct 2026

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

ToolWhat it is for
API-create-a-commentLeaves a new comment on a page or adds a reply to an existing discussion.
API-create-a-data-sourceMakes a new database table under a page, with the columns you describe.
API-delete-a-blockMoves one block, such as a paragraph or to-do, to the trash.
API-move-pageMoves a page under a different parent page or database.
API-patch-block-childrenAdds new blocks to the end of a page, or after a block you pick.
API-patch-pageChanges a page's properties, icon or cover, or sends it to the trash.
API-post-pageCreates a page, either under another page or as a new row in a database.
API-post-searchFinds pages and databases the integration can see by matching their titles.
API-query-data-sourcePulls rows from a database using filters and sort order.
API-update-a-blockEdits the text or settings of an existing block.
API-update-a-data-sourceRenames a database or changes its columns.
API-update-page-markdownRewrites a page, or swaps out parts of it, using Markdown.

Only reads12 tools · Looks things up and changes nothing.

ToolWhat it is for
API-get-block-childrenLists the blocks nested inside a page or another block, one page of results at a time.
API-get-selfShows which bot user the token belongs to, handy for checking the connection works.
API-get-userLooks up one person or bot in the workspace by id.
API-get-usersLists the people and bots in the workspace.
API-list-data-source-templatesLists the page templates set up on a database.
API-retrieve-a-blockFetches a single block and its content.
API-retrieve-a-commentReads the comments left on a page or block.
API-retrieve-a-data-sourceReturns a database's columns and settings so the agent knows its shape.
API-retrieve-a-databaseGets a database's details, including the ids of the data sources inside it.
API-retrieve-a-pageFetches a page's properties, such as its title, status and dates.
API-retrieve-a-page-propertyReads one property in full, useful when a relation or rollup has many entries.
API-retrieve-page-markdownReads 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.

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:

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.

Integration Access tab

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

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.

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:

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

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

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.

Server URL
https://mcp.notion.com/mcp

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

SettingWhat it does
NOTION_TOKENEnvironment variable · requiredYour internal integration secret from Notion's integrations page. The simplest way to sign in.ntn_xxxxxxxx
OPENAPI_MCP_HEADERSEnvironment variableAn 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 flagChoose stdio (the default) or http to run it as a local web server.--transport http
--portCommand line flagPort for the HTTP mode. Defaults to 3000.--port 8080
--auth-tokenCommand line flagBearer token clients must send in HTTP mode. One is generated for you if you leave it out.--auth-token your-secret
AUTH_TOKENEnvironment variableThe same bearer token as --auth-token, set through the environment.
--enable-token-passthroughCommand line flagLets 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 flagTurns 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.

notion-mcp-sm

This project implements an MCP server for the Notion API.

mcp-demo


⚠️ 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 by query-data-source
  • update-a-database - replaced by update-a-data-source
  • create-a-database - replaced by create-a-data-source

New tools (7):

  • query-data-source - Query a data source (database) with filters and sorts
  • retrieve-a-data-source - Get metadata and schema for a data source
  • update-a-data-source - Update data source properties
  • create-a-data-source - Create a new data source
  • list-data-source-templates - List available templates in a data source
  • move-page - Move a page to a different parent location
  • retrieve-a-database - Get database metadata including its data source IDs

Parameter changes:

  • All database operations now use data_source_id instead of database_id
  • Search filter values changed from ["page", "database"] to ["page", "data_source"]
  • Page creation now supports both page_id and database_id parents (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-database is still available and returns database metadata including the list of data source IDs. Use retrieve-a-data-source to 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). Pass include_transcript: true to inline meeting-note transcripts.
  • update-page-markdown — Edit a page's content with Markdown (PATCH /v1/pages/{page_id}/markdown). Prefer replace_content to overwrite the whole page, or update_content for 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.

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:

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.

Integration Access tab

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

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.

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:

Copying your Integration token from the Configuration tab in the developer portal

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:

  1. The Notion-Token header (preferred — unambiguous, and works alongside the server's own Authorization gateway auth). If present it must be a valid Notion token, otherwise the request is rejected with 401.
  2. 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.
  3. 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_, legacy secret_) 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
  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

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

  1. Run npm link command from repository root to create a machine-global symlink to the notion-mcp-server package.
  2. Merge the configuration snippet below into Cursor's mcp.json (or other MCP client you want to test with).
  3. (Cleanup) run npm unlink from 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
  • Basic Memory

    Long-term memory as plain Markdown files you own.

    Tools
    27
    Runs on
    Your computer
    Licence
    AGPL-3.0-or-later
    Stars
    4.4K
  • LinkedIn MCP Server

    Read LinkedIn profiles, companies and job posts with your own login.

    Tools
    20
    Runs on
    Your computer
    Licence
    Apache-2.0
    Stars
    4K
  • arXiv MCP Server

    Search arXiv, download papers and read them in full.

    Tools
    19
    Runs on
    Your computer
    Licence
    Apache-2.0
    Stars
    3.2K
  • TradingView MCP

    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
Full docs on GitHubmakenotion/notion-mcp-server

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