Notion MCP With Claude Code: Install, Connect and Use

To connect Claude Code to Notion, run claude mcp add --transport http notion https://mcp.notion.com/mcp, then type /mcp in Claude Code and complete the OAuth sign-in in your browser. That uses Notion MCP, the remote server Notion hosts and maintains. Once connected, Claude Code can search your workspace, fetch pages and databases, create and update pages, query databases, and comment, with the same access you have in Notion. Some features, such as searching connected apps and heavier database queries, depend on your Notion plan.

Below: the install and sign-in, the tools you get, what depends on your plan, the rate limits, and the habits that keep it safe. If you are new to MCP, what MCP is covers the basics.

Step 1: add the server

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

This is the command in both Notion’s developer documentation↗ (opens in a new tab) and Claude Code’s own MCP guide. Streamable HTTP is the recommended transport; Notion also runs an SSE endpoint at https://mcp.notion.com/sse, but only as a fallback for clients that cannot do streamable HTTP, and Claude Code can.

Choose a scope as you add it. The default, --scope local, keeps Notion to you in the current project. --scope user makes it available in all your projects, which suits Notion, since your notes are rarely tied to one repository. --scope project writes it to .mcp.json for your team to commit; each person then signs in with their own Notion account.

Notion also publishes a Notion plugin for Claude Code, which adds the same MCP server along with Skills and slash commands for common Notion workflows. The plain command above is all you need to start.

Step 2: connect your workspace

1. Start Claude Code and type /mcp.
2. Choose notion. It shows as not authenticated; choose to authenticate.
3. Your browser opens on Notion. Sign in, pick the workspace you want Claude Code to use, and approve.
4. Back in Claude Code, /mcp shows the server connected and how many tools it has.

The connection is to one workspace, and Claude Code’s documentation↗ (opens in a new tab) says tokens are stored securely and refreshed automatically. What happens during that browser step is explained in how MCP sign-in works. One thing Notion is clear about: there is no non-interactive option yet. Notion MCP requires the OAuth flow, and Notion says support for automated workflows is being worked on. The older open-source notion-mcp-server does accept a bearer token, but Notion says it is no longer actively maintained and recommends the hosted server for most people.

Notion’s documentation also points to /context in Claude Code, which shows how much of the session’s context each enabled MCP server is using. Worth a look once, because tool definitions take space before you have asked anything.

What the tools do

Notion publishes the tool list↗ (opens in a new tab). The ones you will use most:

• notion-search: keyword search across the workspace, with filters for location, creator, date and title, up to 50 results.
• notion-ai-search: searches Notion and, where connected, sources such as Slack, Google Drive and Jira, with a natural-language question.
• notion-fetch: reads a page, database, data source or saved view by URL or ID, including a database’s schema and templates.
• notion-create-pages and notion-update-page: create pages (optionally from a database template) and change properties or content. Updates work as search-and-replace on the page’s content, and fail without changing anything if a match is not found.
• notion-query-data-sources: read rows from a database, run a saved view, or query with SQL.
• notion-create-comment and notion-get-comments: comment on a page or a block, and read discussions, including resolved ones.
• notion-create-database, notion-create-view and notion-update-view: build databases and board, table, calendar or timeline views.
• notion-move-pages, notion-duplicate-page, notion-get-users, notion-get-teams and notion-create-file-upload (single files up to 20 MiB, and your workspace’s own file-size limits still apply).

There are more, including tools for Notion Skills, meeting notes and Custom Agent sessions, and notion-get-tool-access, which reports which tools and options your workspace’s plan allows. If a request behaves oddly, asking Claude Code to call that tool first is a quick way to see why.

Prompts worth trying

• “Fetch the spec at this Notion link and list what is not yet implemented in this repository.”
• “Search Notion for our API naming conventions and check src/routes against them.”
• “Create a page under Engineering Notes summarising the changes on this branch, with the commit list.”
• “In the Bugs database, find rows with status In Progress assigned to me.”
• “Comment on the Release checklist page that the migration step is done.”

What depends on your plan

Every tool is listed on every plan, but some only work fully on higher ones. Notion’s documentation describes these, in its own terms:

• Searching connected apps with notion-ai-search requires Notion AI. Without it, the search falls back to Notion content only, with a notice.
• Some search filters and sorts, such as by last editor, last-edited date, multiple teamspaces or title only, need a Business or Enterprise plan. Unavailable options are dropped with a notice rather than failing the call.
• SQL across data sources is unlimited on Business and Enterprise plans with Notion AI. Other plans share a per-workspace allowance for single-data-source queries. Running a saved view has no tool-specific quota on any plan.
• Meeting notes and Custom Agent sessions need a Business plan or higher with Notion AI.

Rate limits

Notion applies its standard API request limits to each user’s use of Notion MCP, counted across all tool calls. Notion’s API reference↗ (opens in a new tab) currently gives each connection 180 requests a minute on most plans and 600 on Business and Enterprise, with a separate limit shared across the workspace. notion-search has a stricter limit of its own: 30 requests a minute. If Claude Code runs many searches in parallel it can hit that; ask it to search less and fetch more, or wait and retry. Notion retries a rate limit once if the wait is two seconds or less; otherwise the tool returns an error saying how long to wait.

Permissions and safe habits

Notion MCP works within your access: it can read and change what you can, and nothing more. The reverse matters just as much. If you can edit your company handbook, so can Claude Code. Notion’s own security guidance↗ (opens in a new tab) adds three points worth following:

• Treat what the tools return as untrusted. A page can contain text written to redirect an assistant. Review proposed actions before approving them.
• Keep confirmation on for anything that changes content. In Claude Code, pre-approve reads such as mcp__notion__notion-fetch and mcp__notion__notion-search if you like, and leave creates and updates on ask.
• Remember that a connected client can send what it reads to other places, including other MCP servers in the same session.

On the admin side, workspace owners manage MCP connections↗ (opens in a new tab) under Settings, Connections, and organisation owners can list and revoke members’ connections through Notion’s Admin API. On Enterprise, admins can also keep an allowlist of the AI tools that may connect. On your own machine, claude mcp logout notion clears the sign-in and claude mcp remove notion removes the server.

Where a task board fits

Notion is a flexible home for documents and databases, and many teams keep their writing there. If you want the doing to happen on a simpler board your assistant works as a member of, with a role on the board and a signed history of every change, fenbs does that, and a task can link to the Notion page it came from. See fenbs vs Notion for where each fits, and the Claude Code integration for setup.