Notion MCP server: setup, tools and limits for teams

Updated 8 min read

Notion MCP is Notion’s hosted MCP server at https://mcp.notion.com/mcp. Add that URL to Claude Code, Cursor, Codex or another MCP client, sign in with OAuth, and the agent can search, read, create and update the pages and databases you can already access. Notion also has an open-source server that runs locally with an integration token, but Notion now says it is no longer actively maintained, so use the hosted one unless you need token auth.

The setup steps below are from Notion’s developer docs and help center, read on 12 October 2026. We have not run Notion MCP ourselves.

Does Notion have an official MCP server?

Yes, two of them:

Notion MCP (hosted) notion-mcp-server (open source)
Runs on Notion’s servers, https://mcp.notion.com/mcp Your machine, with npx or Docker
Sign-in OAuth, each person with their own account An integration token (NOTION_TOKEN)
Reaches Everything the signed-in person can access Only pages and databases shared with the integration
Search AI search on some plans, keyword search otherwise Keyword search only
Status Actively maintained, gets new tools No longer actively maintained
License Hosted service MIT

On 12 October 2026 the open-source repository had 4,666 stars, 634 forks and 201 open issues and pull requests. Its latest release is v2.1.0, from 31 January 2026. The README says issues and pull requests are not actively monitored and that Notion may sunset the project.

Notion’s FAQ points most users to the hosted server. The open-source one is for people who need bearer-token auth for automated workflows or the older JSON-based API tools, and who are willing to run it themselves.

How do I add Notion MCP to Claude Code?

From Notion’s connect guide, run this in your terminal:

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

Then start Claude Code, run /mcp, pick Notion and complete the OAuth flow in your browser. /context shows how many tokens each enabled server’s tools take.

The default scope is local (you, this project). --scope user makes it available in all your projects, and --scope project writes it to .mcp.json so the team gets it through git. Committing the config shares the server address and nothing more. Each teammate still signs in with their own Notion account and gets the access they already have in Notion. Our Claude Code MCP guide covers scopes and /mcp in detail.

Notion also publishes a Claude Code plugin (makenotion/claude-code-notion-plugin on GitHub) that adds the server plus skills and slash commands for common Notion tasks.

How do I connect Notion MCP to Cursor and Codex?

For Cursor, create .cursor/mcp.json in the project root, or ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

Then open Customize in Cursor’s sidebar, enable Notion and complete the OAuth flow. The Cursor MCP guide explains where Cursor reads MCP config from.

For Codex, add the server to ~/.codex/config.toml, or to .codex/config.toml in the project root to share it:

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

Then sign in:

codex mcp login notion

The Codex MCP guide has more on Codex’s config.

Notion’s page also has steps for VS Code, Hermes, Devin, Antigravity, fx and Pi. For any other client, Notion lists Streamable HTTP at https://mcp.notion.com/mcp as the recommended endpoint, https://mcp.notion.com/sse as a fallback for clients without Streamable HTTP, and the mcp-remote bridge for clients that only run local stdio servers:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]
    }
  }
}

Antigravity’s built-in Notion entry uses the deprecated open-source package, so Notion recommends adding the hosted URL as a custom server there instead.

Can I use Notion MCP in Claude and ChatGPT?

Yes. Notion’s help center names Claude (Claude Desktop and Claude.ai) and ChatGPT among the apps that connect, either from the Notion MCP gallery or from the app’s own connector settings. The developer docs do not give click-by-click steps for either app, so follow the app’s connector docs; our Claude connectors guide covers the Claude side.

In ChatGPT, Notion drops the notion- prefix from two tools, so notion-search and notion-fetch show as search and fetch. Those are the names OpenAI uses for company knowledge and deep research, and the two tools return OpenAI’s result shape.

What can the Notion MCP tools do?

Notion’s supported tools page lists 36 tools. The ones a team will use most:

  • notion-search searches Notion, and with AI search also connected sources such as Slack, Google Drive and Jira. It takes filters for location, creator, date and title and returns up to 50 results. It also looks up workspace users by name or email.
  • notion-fetch reads a page, database, data source or saved view by URL or ID, including a database’s schema and templates.
  • notion-query-data-sources queries databases with SQL, reads rows from one data source (50 by default, 100 at most) or runs a saved view.
  • notion-create-pages creates one or more pages, optionally from a database template or at the top of a teamspace. With no parent it creates a private page.
  • notion-update-page, notion-move-pages and notion-duplicate-page change existing pages.
  • notion-create-database, notion-update-data-source, notion-create-view and notion-update-view manage databases and their views.
  • notion-create-comment, notion-get-comments, notion-get-users and notion-get-teams cover discussion and people.
  • notion-create-file-upload uploads one file of up to 20 MiB.
  • notion-get-tool-access reports which tools and options the workspace’s plan allows.

Page content goes in and out as Notion-flavoured markdown. Large writes can run as background tasks: pass allow_async: true and poll notion-get-async-task until the task succeeds.

What are Notion MCP’s limits?

The help center says MCP tools act with your full Notion permissions, so an agent can reach everything you can. Workspace owners manage MCP client access in Settings, then Connections. On the Enterprise plan, admins can restrict members to an approved list of AI apps and use enterprise-managed connections through Okta. Organization owners can list and revoke members’ connections through the Admin API. Per the help center, admins cannot yet see which users use each tool.

Sign-in is interactive. Notion’s FAQ answers “Can I use Notion MCP without interactive authorization?” with “Not yet”. An agent running in CI, on a schedule or on a server needs someone to finish OAuth in a browser, or else the unmaintained open-source server with a token. When an organization shares one connection, the Devin section of Notion’s docs suggests a Notion service account.

Notion MCP uses the standard Notion API request limits, and every tool call counts against them. If the wait is 2 seconds or less it retries once; otherwise it returns a rate_limited error with retry_after_seconds. Notion’s advice is to have the agent run fewer operations in parallel.

Some features depend on the plan. AI search needs a Business or Enterprise plan with Notion AI; other plans get keyword search. Filtering by editor, last-edited date, title only, content status or several teamspaces, and sorting by date, need Business or Enterprise. Querying several databases at once needs Business or Enterprise with Notion AI, and other plans get metered single-database queries. notion-get-tool-access tells an agent what its workspace allows.

Notion’s help center also advises starting with single-player use cases, where one person connects their own AI apps.

How do I run the open-source Notion MCP server?

If you still need it, the README’s setup is: create an internal integration at https://www.notion.so/profile/integrations, share the pages and databases it may use under the integration’s Access tab, then add the server to your client:

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Giving the integration only the “Read content” capability makes it read-only. Its tools map to Notion API endpoints (such as query-data-source and move-page) plus two markdown tools for reading and editing page content. Keep the token out of git.

Should agents write what they learn into Notion?

Reading Notion is the easy case. People already keep specs, meeting notes and project databases there, and an agent should read them. Writing needs more thought, mostly about volume.

Agents that keep notes write many small, linked pages, and they write them fast. We run several agents that share one wiki; on 12 October 2026 it held 107 pages and 565 links between them. In another workspace we run, agents wrote 189 pages on its first day. In Notion, each of those writes would be a tool call against the API limits and a page in a workspace your people browse and search. Each agent would also need a person to sign it in.

Notion is the right home when what agents write is meant for people (status pages, specs, database rows), your team already works there, agents mostly read, or you want AI search across Slack and Drive from one place. A separate wiki the agents keep fits better when agents write many notes, run unattended, come from different vendors and need one shared memory, or when you want to see what they know apart from your human docs. Plenty of teams do both: agents read requirements from Notion and keep their working notes elsewhere.

The company wiki guide covers where team knowledge should live, and wiki vs fact memory compares linked pages with stored facts. For Confluence and Jira, the same question comes up in Atlassian MCP.

A wiki your agents keep: Dexio

Dexio is a hosted wiki for AI agents. Claude Code, Codex, Cursor, Claude, ChatGPT and other MCP clients list, read, search, write, edit, move and link markdown pages, and people see what their agents know as a page graph at https://app.dexio.wiki. Every agent connects to the same server, https://app.dexio.wiki/mcp, so the whole team’s agents share one context, and each change records which agent made it.

Agents that run commands connect with an API key in a header, so they need no browser step and can run headless. Claude and ChatGPT connect as connectors with OAuth. To connect one, send it:

Connect yourself to my Dexio wiki. The steps are at https://dexio.wiki/agents.md: read the whole file, not a summary, and follow them.

Dexio is open source (AGPL-3.0) and free for one person. Team is $10 and Business $20 a member a month; agents never count as members and there are no usage charges. Any wiki downloads as markdown at any time.

FAQ

Is Notion MCP free?

Notion’s docs do not list a separate price for MCP. The tools page says tools are listed on every plan, and that AI search, some search filters and multi-database queries need Business or Enterprise.

What is the difference between Notion MCP and the Notion API?

The hosted MCP server is built on the Notion API and shares its request limits. The API is for code you write; MCP gives an agent ready-made tools and handles sign-in with OAuth.

Is the Notion MCP server open source?

The old local server is, under the MIT license, but Notion no longer actively maintains it. The hosted server at mcp.notion.com is Notion’s own service.

Sources

Ask a question

Ask anything about Dexio.

About
We reply by email.