How to set up the Notion MCP server

Governing MCP across your organization?

Speakeasy’s AI control plane connects, secures, and observes every agent and MCP server from one entry point — with SSO, RBAC, runtime guardrails, and a full audit trail.

Notion has an official MCP server, hosted by Notion at https://mcp.notion.com/mcp. It works on every Notion plan, and it lets an AI agent search your workspace, read pages and databases, and create or update pages for you.

This guide shows you how to connect the Notion MCP server to Claude Code and Codex. You’ll add the server to your agent, sign in to Notion to approve access, and try it with a prompt that reads your workspace and one that writes to it.

/MCP Gateway

One URL for every MCP

Point Claude Code, Cursor, and Copilot at one URL. SSO, per-team policy, and an audit log on every tool call are already built.

Start free

Prerequisites

To follow along, you’ll need:

• A Notion account that’s a member of the workspace you want to connect. Guests can’t connect to Notion MCP.
• Claude Code or Codex CLI installed

Connect your agent to the Notion MCP server

Follow the instructions for the agent you use: Claude Code or Codex. For any other agent, see Connect other MCP clients.

Both agents sign in to Notion with OAuth, so you don’t need to create or copy a token. Your agent gets the same access to pages and databases that you have in Notion.

Claude Code

Add the Notion MCP server to Claude Code:

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

The --scope user option makes the server available in all your projects.

Then sign in to Notion:

claude mcp login notion

Claude Code opens the Connect with Notion MCP page in your browser. Under Select workspace, choose the workspace you want to connect. Select I recognize and trust this URL, then click Continue.

The terminal confirms the sign-in:

Authenticated with "notion". Its tools are now available in Claude Code.

You can also sign in from inside Claude Code. Enter /mcp and follow the prompts for the notion server.

Check that the server connects:

claude mcp list

The notion server shows as Connected:

notion: https://mcp.notion.com/mcp (HTTP) - ✔ Connected

Start Claude Code with claude and ask it about a page in your workspace, for example:

Find my Q4 launch plan in Notion and list the tasks that aren't done yet, grouped by owner

Replace the page name with one of your own pages.

If Claude Code asks for permission to use a Notion tool, select Yes.

Claude Code searches your workspace, reads the page and its database, and answers.

Codex

Add the Notion MCP server to Codex:

codex mcp add notion --url https://mcp.notion.com/mcp

Codex detects that the server uses OAuth and starts the sign-in straight away:

Added global MCP server 'notion'.
Detected OAuth support. Starting OAuth flow…

Your browser opens the Connect with Notion MCP page. Choose your workspace, select I recognize and trust this URL, and click Continue. The terminal then shows Successfully logged in.

Check the server’s configuration:

codex mcp list

The notion row shows OAuth as its authentication method:

Name    Url                         Bearer Token Env Var  Status   Auth
notion  https://mcp.notion.com/mcp  -                     enabled  OAuth

Start Codex with codex and enter /mcp. The notion server shows as connected (65 tools).

Ask Codex to add something to your workspace, for example:

Add a task to the Launch tasks database in my Q4 launch plan in Notion: Prepare launch email, owned by Elena Ruiz, due November 14, status Not started

Replace the database, page, and task details with your own.

If Codex asks for permission to run a Notion tool, select Allow.

Codex finds the database and adds the task.

The new task appears in the database in Notion.

Use a Notion MCP token instead (Business and Enterprise)

On Notion’s Business and Enterprise plans, you can connect with an MCP token instead of signing in through the browser. This suits agents that run without a browser, such as on a server. Only workspace owners can create MCP tokens.

To create one, open Notion’s Developer portal and select New MCP token. Then save the token as an environment variable in your shell profile:

echo 'export NOTION_MCP_TOKEN="your-notion-mcp-token"' >> ~/.zshrc

Replace your-notion-mcp-token with the token you copied. If you use Bash, write to ~/.bashrc instead.

Open a new terminal window so the variable loads.

Add the server to Claude Code with the token in an Authorization header:

claude mcp add --transport http --scope user notion https://mcp.notion.com/mcp --header 'Authorization: Bearer ${NOTION_MCP_TOKEN}'

Keep the single quotes around the header. They tell Claude Code to save the variable name rather than the token itself, and Claude Code reads the token from your environment when it starts.

Or add it to Codex:

codex mcp add notion --url https://mcp.notion.com/mcp --bearer-token-env-var NOTION_MCP_TOKEN

The --bearer-token-env-var option tells Codex to read the token from the NOTION_MCP_TOKEN environment variable and send it with each request.

Connect other MCP clients

You can connect any MCP client that supports remote (Streamable HTTP) servers. Use these values:

Setting	Value
Server URL	https://mcp.notion.com/mcp
Authentication	OAuth. The client opens Notion’s sign-in page.
Header (MCP token only)	Authorization: Bearer <your Notion MCP token>

If your client only supports local (stdio) servers, run the hosted server through mcp-remote with the command npx -y mcp-remote https://mcp.notion.com/mcp.

Troubleshooting

Claude Code shows Needs authentication

If claude mcp list shows this line, Claude Code has the server but isn’t signed in to Notion:

notion: https://mcp.notion.com/mcp (HTTP) - ! Needs authentication

claude mcp add saves the server without signing in, so you see this until you complete the sign-in. Run the login command and approve access in your browser:

claude mcp login notion

If the sign-in page opens in a browser where you aren’t signed in to Notion, run claude mcp login notion --no-browser instead. Claude Code prints the sign-in URL, and you can open it in the browser you use for Notion.

Next steps

You now have the Notion MCP server connected to your agent. You added the server to Claude Code or Codex, approved access to your workspace in Notion, and tried a prompt that reads your workspace and one that writes to it. Your agent can search your pages, read databases, and create or update content for you.

To keep going:

• Connect more services to your agent with the other guides in Connect popular MCP servers.
• Learn how to get better results from your agent’s tools in Best practices for using MCP tools.
• See what teams build with MCP in MCP use cases.