How to connect Claude Code to Notion
Connect Claude Code to Notion over MCP and verify OAuth by retrieving a decision from a known project page.
Free guide · Updated
Based on official documentation · Checked
Ask your agent
Copy the prompt and paste it into your assistant.
Quick answer
Register Notion’s hosted MCP server in Claude Code, then use /mcp to authorize the intended workspace. Verify the setup by having Claude Code find a known project page and quote one decision with a link to the source.
Prepare a page you can verify
Pick a test workspace or a project page you are comfortable sharing with the connected assistant. Use a distinctive page title and add a short section such as Latest decision so that a search result can be checked against the original.
The connector acts with the permissions of the Notion account that authorizes it and has write tools. Start with approved test content, review the OAuth grant and keep approval enabled for tool calls.
Add the server in your project
Run this command from your project directory. Local scope keeps the configuration for your user in this project.
claude mcp add --scope local --transport http notion https://mcp.notion.com/mcpAuthorize Notion
Start or reopen Claude Code in the same project and run /mcp. Select the Notion server and follow its OAuth sign-in prompt. Check which Notion account and workspace you are authorizing. If your Claude account already has a Notion connector, select the connection you intend to verify and avoid configuring it twice.
Practice
Read a project decision
- Ask: “Search Notion for the page titled Academy onboarding pilot. Read its Latest decision section and return the decision and a direct page link. Make no edits.” Replace the title and section with the names in your test workspace.
- Verify the exact page and decision in Notion before relying on the result.
Output: The correct Notion page link and the decision from the section you selected.
Resolve an empty search
First open the same page in Notion with the account that authorized the connector. If it is visible there, check the selected workspace in /mcp and try the exact title or the known page URL. If project-local setup is missing, reopen Claude Code from the directory where you added the server.
To disconnect, remove the MCP server from the same scope and revoke the corresponding grant in Notion if you want to withdraw access.
claude mcp remove --scope local notionSources