What Is Notion MCP?
MCP (Model Context Protocol) is an open standard that lets AI assistants use external tools and data sources. Notion MCP is Notion's official, hosted implementation of it: a server that sits between your AI tool and your workspace and exposes Notion as a set of typed tools — search, read page, edit page, query database — instead of a raw API the agent would have to figure out on its own.
The practical difference from the old integration-token workflow is night and day. You authenticate once through OAuth, the agent discovers the available tools automatically, and page content flows as markdown — which is both easier for models to work with and far cheaper in tokens than Notion's block JSON.
Hosted vs Self-Hosted Server
There are two official ways to run it, and one clear default:
| Hosted Notion MCP | Self-hosted (notion-mcp-server) | |
|---|---|---|
| Setup | OAuth, minutes | Integration token + JSON config |
| Where it runs | Notion's infrastructure | Your machine (npx / Docker) |
| Tools | Markdown-optimized, token-efficient | 22 API tools (v2.0), incl. markdown read/write |
| Read-only mode | No — your full permissions | Yes — read-only integration token |
| Support status | Actively developed | May be sunset; not actively monitored |
Use the hosted server unless you specifically need read-only scoping or an air-gapped setup. Notion has said plainly that the open-source notion-mcp-server on GitHub is no longer the priority and may be retired.
Setup: Claude Code, Claude Desktop, Cursor, ChatGPT
Claude Code (one command)
claude mcp add --transport http notion https://mcp.notion.com/mcpOn the next run, Claude Code opens the OAuth flow; approve access and the Notion tools appear automatically.
Claude Desktop
Settings → Connectors → add Notion from the directory (one click), or add a custom connector with the URL https://mcp.notion.com/mcp.
Cursor
Add to .cursor/mcp.json (project) or the global MCP settings:
{
"mcpServers": {
"notion": { "url": "https://mcp.notion.com/mcp" }
}
}ChatGPT and others
Any tool that can act as an MCP client can connect — ChatGPT supports it through connectors. Tools without MCP support can't use Notion MCP at all, which is the most common reason a setup "doesn't work."
Self-hosted variant
Create an internal integration at notion.so/profile/integrations, grant it access to the specific pages you want exposed, then run the server with your token:
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": { "NOTION_TOKEN": "ntn_****" }
}
}
}What Agents Can Actually Do
- Search across your pages and connected content — the agent finds context instead of you pasting it.
- Read pages as markdown — full page content in one call, token-efficient, including meeting-note transcripts.
- Write and edit — create pages, overwrite content, or make targeted find-and-replace edits.
- Work with databases — query data sources with filters and sorts, update properties, create entries.
- Move and organize — reparent pages, manage structure.
In practice that covers the whole loop of an LLM wiki: the agent ingests sources, writes summaries back into Notion, cross-links pages, and answers questions from what it already built. We run this exact setup daily — copy-paste recipes are in Claude Code + Notion: Five Workflows, and the full build story with honest limitations is in LLM Wiki for Notion.
Security and Permissions
- Your permissions are the ceiling. An agent connected through Notion MCP can access exactly what your account can — nothing more, and it cannot bypass page-level permissions.
- The floor is up to you. The hosted server always acts with your full access, so think before connecting an experimental agent to a workspace with sensitive data. For read-only access, use the self-hosted server with a "Read content"-only integration token.
- Enterprise controls. Workspace admins on Enterprise can enable MCP Governance: an approved list of AI apps, connection auditing, and a disconnect-all switch.
- Data flows to the model. Whatever the agent reads becomes part of its context — treat the AI tool's own data policy as part of your security surface.
The Missing Map: What MCP Doesn't Give You
MCP gives an agent hands — search, read, write. It doesn't give it eyes. Every query is a keyhole view: the agent sees the pages it fetched this turn, not the shape of the workspace — which pages are hubs, which clusters exist, where the orphans are. That's a graph problem, not a retrieval problem.
This is exactly the layer IVGraph adds on top of a Notion + MCP setup: the workspace rendered as an interactive 3D knowledge graph for you, and the same structure exposed programmatically for agents via the IVGraph LLM API — search, node neighborhoods, and shortest paths between pages. The agent edits through MCP; the graph shows both of you what the workspace actually looks like.
FAQ
What is Notion MCP in one sentence?
Notion's hosted MCP server that lets AI tools like Claude, Cursor, and ChatGPT securely read and write your Notion workspace through OAuth, within your existing permissions.
What's the server URL?
https://mcp.notion.com/mcp — add it in any MCP-capable client; in Claude Code it's claude mcp add --transport http notion https://mcp.notion.com/mcp.
Is there a separate charge for Notion MCP?
No separate product to buy — you connect with your existing Notion account, and agents see the content your plan already includes. The AI tool on the other end (Claude, Cursor, ChatGPT) has its own pricing.
Hosted or GitHub version?
Hosted, unless you need a read-only token or a fully local setup. The GitHub server still works but is no longer actively supported and may be sunset.
Is there an MCP for Obsidian too?
Yes — community MCP servers exist for Obsidian vaults (local markdown makes it straightforward). The pattern is the same; only the storage differs. If your knowledge lives in Notion, Notion MCP is the native route.