NotionCAUTION
Notion MCP server for Claude, Cursor, ChatGPT & Claude Desktop. Connect AI agents to Notion via Model Context Protocol — pages, databases, blocks, comments, files.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://www.npmjs.com/package/notion-mcp-server)
Give your AI read/write access to Notion with one token and one command. Claude Code, Claude Desktop, Cursor, VS Code, Cline, Zed, anything that speaks MCP: it can create pages, query databases, append blocks, apply templates, comment and upload files, in plain language.
Notion ships its own MCP server. Where this one differs:
- It authenticates with a token, so it runs headless. Notion's hosted MCP is OAuth-only and someone has to click "Authorize". This one works in CI, cron jobs, background agents and self-hosted deployments.
- It doesn't spend your context on tool schemas. The official open-source server loads 24 endpoint schemas into the model's context at connection: 17,163 tokens, re-sent with every request for the rest of the session. This one loads three tools, 1,005 tokens — 94% less, 17× smaller — and fetches an operation's schema only when a task actually touches it.
- It doesn't spend your context on answers either. Reading the same pages through both servers, pulling a page's content costs 82% less (26,071 → 4,568 tokens on an 88-block page), a 25-row database query 81% less, a page object 68% less. Notion's raw JSON is mostly
id/typewrappers,annotations, andcreated_by/parent/iconblocks, and none of it reaches the model. That is the half that compounds, because a tool surface is paid once and responses are paid on every call. Measured against a reproducible fixture, with the caveats stated →
Nothing is lost to get
4ba112bba8efOBSERVED · 2026-10-06Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add notion-mcp-server --env NOTION_TOKEN=${NOTION_TOKEN} -- npx -y [email protected]Exposed tools (1)
1 read · 0 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
notion_describe | read |
Trust audit
CAUTIONgrade B · trust 83/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (2 observation(s))
- Network
- none-observed
- Shell
- declared (1 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (18)
| "😶🌫️"
| "😶🌫"
| "😮💨"
| "😵💫"
| "❤️🔥"
const pkg = require("../../package.json") as { version: string };source: { type: "path", path: "../../etc/passwd" },"https://169.254.169.254/latest/meta-data/",
# -> notion-mcp-server vX.Y.Z running on http://127.0.0.1:3000/mcp
curl http://127.0.0.1:3000/health
npx @modelcontextprotocol/inspector --transport http --server-url http://127.0.0.1:3000/mcp
test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]"https://169.254.169.254/latest/meta-data/",
@notionhq/client, remark-gfm, remark-parse, unified, zod, @types/mdast, @types/node, shx
- **MCP protocol revision 2026-07-28, over HTTP and stdio.** The server now serves the stateless generation of the protocol next to the 2024-11-05 ... 2025-11-25 one, choosing per request from what th
- **Server logs reach the MCP client.** The server only ever logged with `console.error`, and most clients hide a server's stderr — VS Code, MCP Inspector and Claude Desktop show `notifications/messag
- **Streamable HTTP transport.** The server can now run as a remote/hosted endpoint in addition to stdio. Set `MCP_TRANSPORT=http` (default stays `stdio`) to serve the MCP Streamable HTTP protocol at
It serves MCP **Streamable HTTP** on `/mcp` for both current protocol generations, picked per request from what the client sends. **MCP 2026-07-28** clients get the stateless path, where every `POST`
Gates applied: no_behavioural_pass.
4ba112bba8effull audit observations/trust-audit/mcp-server/awkoy__notion-2.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-06 | 4ba112bba8ef | CAUTION | B | 83 | first audit |
Questions
What is the Notion MCP server?
Notion MCP server for Claude, Cursor, ChatGPT & Claude Desktop. Connect AI agents to Notion via Model Context Protocol — pages, databases, blocks, comments, files.
What tools does Notion expose?
1 in total: 1 read-only, 0 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is Notion safe to connect to an agent?
With care. The audit graded it B (83/100) and found 18 things worth knowing before you trust this server, listed below with the exact line each was found on.
What credentials does Notion need?
It reads NOTION_TOKEN from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does Notion run?
It speaks stdio and streamable-http, so it runs as a local process your client starts. It is published on npm as notion-mcp-server at 3.1.2.
How current is this page?
The grade is for one exact copy of the source (4ba112bba8ef), read on 2026-10-06. The repository is watched and re-audited when it changes.