Run claude mcp add --transport http notion https://mcp.notion.com/mcp, then type /mcp in Claude Code and sign in to Notion. After that, Claude Code can read and update the content you can access in that workspace.

It’s a good fit for searching, creating pages and updating database rows. For drafting a long document, I’d keep the draft in a file and copy it to Notion later. Notion vs. Markdown files for Claude Code explains why.

The steps below come from Notion’s documentation, read on September 18, 2026. We also read the server’s tool descriptions through a Claude connection that day. We haven’t timed anything.

How do I connect it?

  1. In a terminal, run:

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

  2. Start Claude Code, type /mcp, choose Notion and finish the sign-in in your browser.

  3. Try it: Search my Notion for the onboarding checklist and summarize it.

Notion’s setup guide says that after you authorize, “the client can read and update content that you can access in the selected Notion workspace.” You don’t share pages with it one by one.

Two other ways in:

  • The Notion plugin. In Claude Code, run /plugin marketplace add makenotion/claude-code-notion-plugin, then /plugin install notion-workspace-plugin@notion-plugin-marketplace, and restart. The plugin connects the same server and adds four skills and commands such as /Notion:search and /Notion:create-page.

  • Codex. Add this to Codex’s config file, then run codex mcp login notion:

    [mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

Older guides have you create an integration token and share each page with it. That’s Notion’s open-source server, which the setup guide says “is no longer actively maintained.” Use the hosted one above.

What can Claude Code do in Notion?

The server lists more than 30 tools. The ones you’ll use most:

  • Search the workspace, and open a page, database or view by its link.
  • Create pages, update their content and properties, move and duplicate them.
  • Create databases and views, and query rows.
  • Read and add comments, on the page or on a block.

Some tools depend on your plan. AI search needs Notion AI. Row queries are metered unless you’re on Business or Enterprise with Notion AI, and querying meeting notes needs Business or higher.

What can’t it do, or does badly?

Claude edits a page as Notion-flavored Markdown, and some things don’t fit in that format:

  • It can’t merge table cells. The server’s instructions tell it to say you “must do it in the UI.”
  • It can’t edit a meeting transcript.
  • Blocks the API doesn’t support yet come back as <unknown> tags. Claude is told to check how many there were before it relies on what it read.
  • Tables, multi-line quotes and blank lines are written differently from standard Markdown, so check them after Claude writes a page. The comparison lists the rules.

Search is limited to 30 requests a minute. Large writes can run in the background, and Claude has to ask the server when they’re done.

Why does it use so many tokens on long pages?

The fetch tool has no option to read part of a page. It returns the whole page, even when Claude needs one paragraph. With files, Claude Code can search first and read only the lines around a match.

Claude Code also caps what one MCP call can return. It warns when a tool’s output passes 10,000 tokens and cuts it off at 25,000 by default. If a long page comes back incomplete, raise the limit before you start Claude Code:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Splitting a long page into child pages helps more, because Claude can then fetch only the part it needs.

Tool descriptions are less of a problem than they were. With tool search, now the default, Claude Code loads MCP tool definitions when it needs them, not all at the start.

When should I write in files instead?

When the document is long and you’ll revise it many times. Claude Code reads and edits a file directly and can search the folder around it. If you use Git, it keeps every version. You can still copy the result to Notion for comments. The comparison has the steps. If you’d rather leave Notion for writing, see AI-native Notion alternatives.

StashBase is an open-source app for writing in a local folder with Claude Code, Codex or Antigravity. You can read and edit documents beside the chat and review the agent’s file edits. It doesn’t sync between devices.