Notion MCP Server

Official Notion MCP server that lets AI agents search, read, and edit pages and databases in a Notion workspace.

Description

The Notion MCP Server implements the Model Context Protocol and gives AI agents access to a Notion workspace: search pages and databases, read and write page content as Markdown, query and create database entries, move pages, and create comments. Notion lists 22 tools that are deliberately designed for low token consumption; page content is passed as Markdown instead of block JSON.

Notion runs the server as a hosted remote service at https://mcp.notion.com/mcp (Streamable HTTP), with https://mcp.notion.com/sse as a fallback path. Sign-in uses an OAuth authorization flow: the client opens a browser window where you confirm the connection for your workspace. No local process is required.

Self-hosting option

Alternatively, the open-source package @notionhq/notion-mcp-server (MIT license, version 2.5.1 at the time of review) can be run locally via npx or as the Docker image mcp/notion. Here authentication uses an integration token (NOTION_TOKEN) from an internal Notion integration. Per the README, Notion now prioritizes the hosted server and may sunset the self-hosting repository in the future.

Setting up the hosted option in Claude Code:

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

Why the hosted option is preferred

Notion has clearly shifted priority to the hosted server because it requires no local processes, no separate token management, and no update maintenance: a single OAuth click is enough, and Notion handles operation and updates. The self-hosting package remains functional but, per the README, is only maintained at a lower priority and may be discontinued in the future. For new connections, the hosted option is therefore the obvious choice, while existing self-hosting setups don't need to migrate immediately.

Typical use cases

The server suits tasks such as automatically summarizing long knowledge-base pages, creating structured meeting notes directly from a conversation with the agent, maintaining task lists in a Notion database, or searching a workspace for information spread across multiple pages. Thanks to its token-efficient Markdown responses, the server also works well for workflows with many consecutive Notion queries without quickly filling up the model's context window.

Who the Notion MCP Server fits

Teams that already use Notion as a central knowledge base or project management tool benefit the most, since it lets an AI agent plug directly into existing workflows without manually copying content. For individuals who only use Notion occasionally, the effort of setting up an integration is less worthwhile; the regular Notion interface is often enough.

Frequently asked questions

Do I need to know how to code to use the Notion MCP Server? No, the hosted option can be set up code-free via OAuth; only the self-hosting option requires working with npx, Docker, or an internal integration. Can the agent accidentally delete content? Only within the granted scope; a tightly scoped integration or OAuth grant significantly reduces that risk. Does the server work with private Notion workspaces? Yes, access is determined exactly by the workspace and pages for which the connection was confirmed.

Requirements

A Notion account with access to the target workspace. The hosted option only needs an MCP client that supports remote servers over HTTP and OAuth. The self-hosting option additionally requires Node.js (npx) or Docker plus an internal Notion integration with a token.

Installation instructions

The Notion MCP Server can be connected in two ways: as a Notion-hosted remote service with OAuth sign-in, or as a locally run self-hosted server with an integration token. Notion now recommends the hosted option.

Quick start

For the hosted option, register the remote server in your MCP client, e.g. in Claude Code with claude mcp add --transport http notion https://mcp.notion.com/mcp, in Cursor via an mcpServers entry with "url": "https://mcp.notion.com/mcp", or in VS Code via a servers entry with "type": "http". On the first call the client opens the OAuth dialog; select the workspace there and confirm the connection.

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

For the self-hosting option, create a token in the internal integration at notion.so/profile/integrations, grant the desired pages in the integration's Access tab (or choose "Connect to integration" from the three-dot menu on the target page), and start the server via npx with NOTION_TOKEN set as an environment variable. A Docker image mcp/notion is also available.

Which option fits

The hosted option is the quickest to set up, needs no local process, and handles access through an OAuth dialog. The self-hosting option makes sense when traffic should not leave your own network or when an existing internal integration should be reused. Per the project README, the self-hosting repository is only maintained as a lower priority.

Step 1: Connecting the hosted option

Register the remote server in your MCP client. In Claude Code:

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

In Cursor or VS Code, create a server entry with the URL https://mcp.notion.com/mcp instead (in VS Code with "type": "http"). On the first call the client opens a browser window for OAuth authorization — select the workspace there and confirm. If the primary path fails, https://mcp.notion.com/sse is available as a fallback.

Step 2: Connecting the self-hosting option

Create an internal integration at notion.so/profile/integrations and copy its token. Then, in the integration's Access tab, grant exactly the pages and databases the agent should see — or choose "Connect to integration" from the three-dot menu on the target page. Start the server via npx with NOTION_TOKEN set as an environment variable, or use the Docker image mcp/notion.

Keeping access tight

The agent can read and change anything reachable within the chosen OAuth scope or via the connected integration. For automated workflows, use a dedicated integration with as few granted pages as possible and treat the token like a password. Workspace owners can view and remove connected MCP clients in Notion settings under "Connections".

Step 3: Verifying the setup

After connecting, test with a harmless task such as "Find the page with the onboarding notes and summarize it." Check that only the expected pages appear, and tighten the granted scope if needed.

Common connection issues

If the OAuth login doesn't open in the browser, check whether the client is blocking pop-ups or new windows — some terminal environments without a graphical interface can't launch a browser at all and instead need a manual sign-in via a displayed URL. With the self-hosting option, an expired or revoked integration token causes authentication errors; a fresh token from the account settings usually fixes this immediately.

For teams with multiple workspaces

Anyone using several Notion workspaces in parallel, for example one for their own company and one for a client project, should register the server under different names in the client configuration and explicitly select the correct workspace during each OAuth sign-in. This helps prevent an agent from accidentally making changes in the wrong workspace.

Source: developers.notion.com/docs/mcp and developers.notion.com/docs/get-started-with-mcp, plus github.com/makenotion/notion-mcp-server, checked on 2026-09-05.

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

Authentication

Hosted option: per-workspace OAuth authorization flow, triggered from the client. Self-hosting option: integration token (NOTION_TOKEN) from an internal Notion integration, optionally a bearer token for the HTTP transport.

Required access permissions

Effective permissions match the granted scope: for the hosted option, the OAuth flow determines which parts of the workspace the agent may access; for the self-hosting option, the pages and databases connected in the integration's Access tab determine access. Within that scope, read and write actions are possible (creating pages, editing content, writing comments).

Transmitted or stored data

Requests and tool parameters go to the Notion API. Responses can include content from any granted pages and databases, and are passed to the MCP client and its language model. With the hosted option, the connection runs through Notion's own server at mcp.notion.com; with the self-hosting option, the server runs locally but still calls the Notion API. Workspace owners can manage MCP client access in Notion settings under "Connections".

Security risks

An overly broad OAuth scope or an integration with access to many pages lets an agent — or a compromised client — perform far-reaching read and write actions in the workspace, up to overwriting or moving production documents. Grant only the pages actually needed, use a dedicated integration with narrow access for automated agents, treat the self-hosting token like a password, and regularly review connected clients in Notion settings.

License and costs

License
MIT
Cost
free

The MCP server itself is free; the self-hosting package is open source (MIT license). A Notion account is required — Notion offers a free tier as well as paid plans for team and enterprise features, billed independently of the MCP server.

Alternatives

Not recorded yet.

At a glance

Provider
Notion
Status
Official server
Deployment
Local and remote
Current version
2.5.1
GitHub stars
4,712
Last reviewed
07.09.2026

Repository and documentation

Categories

Supported clients

Related guides

Guides and background related to this entry.

No related guides yet.