Notion MCP Server

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.

Hosted option (recommended)

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:

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.

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.

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.

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.

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

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.

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

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

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.