by awkoy
Notion MCP server with token auth: connect Claude Code, Claude Desktop, Cursor, VS Code and Codex to Notion pages, databases, comments and files. 3 tools, 94% less context than the official server, works on any plan, runs headless.
# Add to your Claude Code skills
git clone https://github.com/awkoy/notion-mcp-serverGuides for using ai agents skills like notion-mcp-server.
Last scanned: 5/30/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-05-30T16:05:42.652Z",
"npmAuditRan": true,
"pipAuditRan": true
}See how notion-mcp-server compares with popular alternatives.
notion-mcp-server is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by awkoy. Notion MCP server with token auth: connect Claude Code, Claude Desktop, Cursor, VS Code and Codex to Notion pages, databases, comments and files. 3 tools, 94% less context than the official server, works on any plan, runs headless. It has 180 GitHub stars.
Yes. notion-mcp-server passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.
Clone the repository with "git clone https://github.com/awkoy/notion-mcp-server" and add it to your Claude Code skills directory (see the Installation section above).
notion-mcp-server is primarily written in TypeScript. It is open-source under awkoy on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh notion-mcp-server against similar tools.
No comments yet. Be the first to share your thoughts!
Based on votes and bookmarks from developers who liked this skill
From $49 · 30 days · terms & refunds
⚠️ Third-Party Software Notice
This skill is third-party open-source software developed and hosted independently on GitHub. SkillsLLM is an informational directory and does not control or maintain the underlying repository.
Any security checks, ratings, or warnings displayed by SkillsLLM are automated and limited in scope. They do not constitute a security certification or guarantee that the software is safe, error-free, or free from malicious code, vulnerabilities, compromised dependencies, or prompt-injection risks.
Review the source code, permissions, dependencies, and configuration before installing or running any third-party skill. Use is at your own risk. To the maximum extent permitted by applicable law, SkillsLLM is not liable for losses arising from third-party software.
Automated security scan — not a certification.
notion-mcp-server is a Model Context Protocol (MCP) server that gives Claude Code, Claude Desktop, Cursor, VS Code, Codex and any other MCP client read/write access to Notion with one token. Your AI can search, create and edit pages, query databases, comment and upload files, in plain language.
1. Get a Notion token. Open app.notion.com/developers/tokens → + New token → name it, pick your workspace → Create token → copy the ntn_… value. A Personal Access Token sees everything you can see, with no per-page sharing. Can't create one? See the other token option.
2. Install it.
npx add-mcp notion-mcp-server --env NOTION_TOKEN=ntn_paste_your_token_here
add-mcp finds the MCP clients on your machine and writes the config for the ones you pick: Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, Cline, Windsurf, Zed and more. Add -g to install for your user instead of the current project.
Keep the
--envflag. Without it the entry is written without a token, and every call fails with an auth error.
Or install in one click:
YOUR_NOTION_TOKEN in the generated entry..mcpb file (or drag it into Settings → Extensions) and paste your token. No Node.js needed. New to all this? The step-by-step walkthrough assumes nothing.Using Claude Code? Install it as a plugin instead. The plugin bundles the server with a Notion workflow skill, which teaches Claude when to search, how to filter a database with where, and how to batch writes. Claude Code asks for the token when you install it (or later with /plugin configure notion-mcp-server@awkoy) and keeps it in your system keychain:
/plugin marketplace add awkoy/notion-mcp-server
/plugin install notion-mcp-server@awkoy
The plugin runs the npm release that matches its own version and needs Node.js 22 or later. It also offers a default parent page and a read-only switch; the plugin's README has the details.
Any client that reads an mcpServers block (Cursor's ~/.cursor/mcp.json, Claude Desktop's claude_desktop_config.json, Cline, Zed, Continue…):
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "notion-mcp-server"],
"env": { "NOTION_TOKEN": "ntn_paste_your_token_here" }
}
}
}
Claude Code:
claude mcp add notion -s user -e NOTION_TOKEN=ntn_paste_your_token_here -- npx -y notion-mcp-server
Codex (~/.codex/config.toml):
[mcp_servers.notion]
command = "npx"
args = ["-y", "notion-mcp-server"]
env = { NOTION_TOKEN = "ntn_paste_your_token_here" }
Gemini CLI: gemini extensions install https://github.com/awkoy/notion-mcp-server asks for the token once and keeps it in your system keychain.
Docker (Podman, OrbStack and colima take the same flags; -i is required for stdio):
claude mcp add notion -s user -e NOTION_TOKEN=ntn_paste_your_token_here \
-- docker run --rm -i -e NOTION_TOKEN ghcr.io/awkoy/notion-mcp-server:latest
3. Try it. In a new chat:
"Use Notion to make a page called 'Hello from my agent' and add a checklist of three things to try today."
Your AI calls notion_write and replies with a link to the new page.
| Best for | Auth | Headless / CI | Notes | |
|---|---|---|---|---|
Notion hosted MCP (mcp.notion.com) |
Interactive chat in claude.ai, ChatGPT, Cursor; Notion AI features | OAuth on every plan. MCP tokens on Business and Enterprise, created by workspace owners | Business and Enterprise only | First-party and the largest tool set (meeting notes, SQL across data sources, Custom Agents); several tools need a paid plan or Notion AI |
| Notion open-source server | — | Token | ✅ | Notion calls it deprecated and "no longer actively maintained" |
| This server | Agents, automation, CI, self-hosting, long sessions | Token, every plan | ✅ | Actively maintained; 3 tools, batched and idempotent writes |
To chat with Notion in claude.ai or ChatGPT, Notion's hosted connector is one click. Use this server when an agent runs unattended, when your plan has no MCP tokens, when context cost matters, or when you want it on your own host. Detailed comparison →
Both go in the same NOTION_TOKEN env var; only where you get them differs.
| Personal Access Token (recommended) | Internal Integration (scoped) | |
|---|---|---|
| Where | app.notion.com/developers/tokens → + New token | app.notion.com/developers/connections → + New connection |
| Scope | Everything you can see | Only pages where you clicked • • • → Connect → <integration> |
| Use when | Default: personal and team workspaces | You can't create a PAT, or an admin wants explicit per-page scoping |
object_not_found on a page you can see? That's an Internal Integration that was never Connected to the page. Connect it, or switch to a PAT.| Env var | Required | Default | Meaning |
|---|---|---|---|
NOTION_TOKEN |
✅ | — | PAT (ntn_…) or Internal Integration secret |
NOTION_PAGE_ID |
— | — | Default parent for create_page / create_database when no parent is passed (page URL or id) |
NOTION_RATE_LIMIT |
— | 3 |
Requests per second (Notion's documented limit) |
NOTION_READ_ONLY |
— | — | true disables every write operation |
NOTION_ALLOWED_OPERATIONS / NOTION_BLOCKED_OPERATIONS |
— | — | Allowlist / blocklist of operations, see Restricting operations |
NOTION_CONFIRM_DESTRUCTIVE |
— | — | true asks you before a destructive operation runs |
NOTION_UPLOAD_ROOT |
— | — | Directory upload_file's local path source is confined to (/ for no limit). Unset: refused over HTTP, dot-named paths and system and app-data folders refused over stdio, see Files |
NOTION_UPLOAD_MAX_BYTES |
— | 1073741824 (1 GiB) |
Largest file upload_file accepts from any source |
NOTION_UPLOAD_URL_TIMEOUT_MS |
— | 30000 |
Time limit for fetching a url source, redirects and body included |
NOTION_UPLOAD_ALLOW_PRIVATE_URLS |
— | — | true lets a url source reach private, loopback and link-local addresses |
NOTION_FILE_URLS |
— | full |
`re |