Connect Claude Code to Notion: Setting Up Notion MCP

"Check my Notion tasks and summarize what I need to do today." "Append this to my household budget page." Once you can ask Claude Code to handle requests like this, you can manage household tasks kept in Notion simply by talking to it. Notion MCP is the gateway that makes this possible.

This article outlines the steps to connect Notion MCP to Claude Code, as well as key caveats I learned from hands-on use.

What Is Notion MCP?

MCP (Model Context Protocol) is a common way for AI tools to connect to and operate external services. Notion provides an official MCP server at the URL https://mcp.notion.com/mcp. Once you register it in Claude Code, you can ask Claude in conversation to "read this page" or "add a row to this database."

You don't need to write any code. You can start using it in just two steps: registration and login.

Setup Workflow

1. 1. Register via CommandRegister the Notion MCP URL using claude mcp add
2. 2. Log in via BrowserAuthorize Notion access from /mcp
3. 3. Test Read AccessAsk it to summarize a page to verify the connection

Step 1: Register via Command

Run the following command in your terminal. This is the exact command for Claude Code provided in Notion's official documentation.

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

The notion in the middle is an identifier you choose yourself. Keep it short and clear, as you will use it later for permission settings and other configurations.

Running this command configures it to be available only within your current directory (project). You can change this scope using --scope.

If you are automating household tasks, setting it to user is convenient so you can use it regardless of which folder you are working in.

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

Step 2: Log in via Browser

Simply registering the server does not yet grant access to Notion content. Launch Claude Code, enter /mcp, and select notion from the list. A browser window will open displaying the Notion login and authorization screen. Select the workspace you want to use and grant access to complete the setup. You can also accomplish the same thing by running claude mcp login notion from your terminal.

Your login credentials are stored by Claude Code and refreshed automatically when they expire, so you do not need to log in again every time.

Once connected, try asking something like: "Find the page titled 'Shopping List' in Notion and summarize its contents in three lines." If it returns the page contents, the connection is working.

If You Already Connected Notion in claude.ai

If you have already added Notion as a connector in the web version of claude.ai, you might not need the steps above. According to Claude Code's official documentation, if you are logged into Claude Code with your claude.ai account, connectors added in claude.ai are automatically available in Claude Code as well. They appear in the /mcp list with an indicator showing they originated from claude.ai.

If you register Notion in both places, two identical Notion entries will appear, so sticking to one avoids confusion.

Differences from the API "Integration"

You can also interact with Notion programmatically through its API. That approach involves creating an "integration (connection)" and running operations using a secret API key (token). Choosing which one to use depends on your use case.

Notion's official documentation explains that, once authorized, the client "can read and update content that you can access in the selected Notion workspace." This is convenient because you do not need to add connections on a per-page basis, but keep in mind that it also means Claude has broader access. Additionally, the documentation notes that authorization requires browser interaction and non-interactive authorization is not yet supported. Even if you plan to use it for automated daily runs, you will still need to complete the initial login manually.

For the common API error where a page cannot be found despite having the correct ID, see Notion API object_not_found (404): What to Check First.

Caveats Learned from Hands-On Use

Decide Where to Write in Advance

MCP can write to anything within the same scope you have access to. If your instructions are ambiguous, it might append content to unintended pages. To be safe, clearly specify the location, such as "Only create new pages under this parent page." If repeating these instructions every time is tedious, add them to CLAUDE.md—a file Claude Code reads every session—so it adheres to them automatically without being reminded.

Have It Read Back After Writing

In my environment, depending on how content was written, line breaks were sometimes inserted literally as the two characters "\n". There were also times when some Japanese characters were replaced with different characters. In both cases, you can catch the issue by having Claude read the page again immediately after writing. Instructing it with "Read the page back after writing and confirm the formatting is intact" gives you peace of mind.

Narrow the Read Scope for Large Pages

If a page or database is large, loading it takes extra time and consumes a substantial number of tokens. Restricting your prompt to only the necessary scope, such as "Only tasks due this week," will speed things up.

Summary

• Notion MCP can be registered with claude mcp add --transport http notion https://mcp.notion.com/mcp and used after logging in via a browser through /mcp.
• Add --scope user to make it available across all directories. If you already connected it in claude.ai, it may work out of the box.
• Because MCP runs with your personal permissions, specify write locations clearly and have Claude read back what it wrote.

When you need a page or database ID, the Notion ID Finder extracts it when you paste the URL.