M
MCP Directory CURATED DIRECTORY
911 MCP servers indexed
中文
← Back to directory
N

Notion MCP Server

Community
A token-auth, headless Notion MCP server for Claude, Cursor, and any MCP client
How to install ↓ Compare GitHub source repository ↗
Category
Collaboration #8 of 55
Stars
★ 177 Popular
Transport
stdio (local process) · Streamable HTTP
Runtime
Node.js · Docker
Credentials
API key / credential required
License
MIT
Last commit
Tools
2
61FMRS · C

A well-documented, agent-first community Notion MCP server. Its two-tool surface with on-demand schemas, batching, idempotency, retries, access controls, and HTTP transport make it a strong fit for unattended and token-sensitive deployments. Caveats: it is not official Notion software, so trust requires auditing or self-hosting, and the HTTP mode must be secured with an auth token.

Strongest · Documentation 17/20 Weakest · Reliability 9/20

Reliability
9/20
Security and permissions
11/20
Maintenance
11/20
Documentation
17/20
Setup experience
13/20
Why each score
Reliability 9/20
The README describes an elaborate architecture (two-tool dispatch over 43 operations, batch/atomic semantics, idempotency cache, token-bucket rate limiting with retry) and claims a vitest suite covering the markdown parser, dispatcher, batch semantics, access control, and HTTP transport. However, no actual test files or CI workflow files were provided for inspection — these are only prose claims in the README, unverifiable from the static material given. The manifest is internally consistent with the README (stdio transport, package name, env vars) with no visible contradictions. Per the static calibration rule, reliability cannot exceed 12 without verifiable CI/test evidence, and the remaining uncertainty pushes the score toward the lower-middle of that range.
Security and permissions 11/20
Credentials are passed via the NOTION_TOKEN env var and correctly flagged isSecret in the manifest. The docs are commendably transparent that a PAT grants the same access as the user's entire workspace, and offer a narrower Internal Integration alternative. NOTION_READ_ONLY and NOTION_ALLOWED_OPERATIONS/BLOCKED_OPERATIONS support least-privilege configuration, and the HTTP transport defaults to loopback with an explicit warning to set MCP_AUTH_TOKEN before exposing it externally. However, by default all write and destructive operations (archive/trash page, delete_block, delete_comment, etc.) are enabled with no confirmation step, and the docs themselves admit that the 'destructive' blocklist does not cover destructive-equivalent actions like update_database's in_trash flag or update_page_markdown replacing page content — a disclosed but unmitigated gap. NOTION_UPLOAD_ROOT is opt-in, so unrestricted file-path reads are the default rather than the exception. Overall, risks are well disclosed with reasonable optional mitigations, but default least-privilege and confirmation gating are incomplete, capping the score in the low-teens.
Maintenance 11/20
The repo carries an MIT license, 165 stars, 12 open issues, is not archived, and is at version 3.0.0 with a MIGRATION.md documenting the v1.x upgrade path — signs of ongoing iteration. However, no commit history, release cadence, issue-response-time data, or dedicated security-response channel (e.g., SECURITY.md) was provided, so governance and update-path maturity cannot be confirmed. Per the rules, this missing evidence is a deduction rather than an assumed positive.
Documentation 17/20
The README is extensive: quick-start blocks for multiple clients, a detailed auth comparison (PAT vs Internal Integration), a full env-var table, operation-restriction guidance, HTTP-transport security notes, a troubleshooting section, an FAQ, and a complete non-developer walkthrough — plus proactive disclosure of real limitations (the destructive-blocklist gap, unrestricted file uploads by default). This approaches the top-tier bar of layered docs with disclosed limitations. Points are deducted because several comparative figures (e.g., '422 tokens' vs '17,163 tokens') rely on an external benchmarks link not included in the material and are unverifiable, and much of the competitive framing reads as marketing rather than neutral documentation.
Setup experience 13/20
The docs offer multiple installation paths — npx, Docker/Podman, a one-click Claude Desktop extension (.mcpb), and a VS Code install badge — with clear, low-friction steps typical of an npm-distributed MCP server. However, per the static calibration rule, setup cannot score above 15 without verifiable CI workflow files and committed tests, none of which were provided for inspection. The score therefore stays under that ceiling and is moderated further for the lack of independently verifiable execution evidence.

Static review · not runListed 2026-09-07

Read the FMRS scoring method →

Fit and risk

What it can accessUses the networkChanges third-party account data

Best for

  • Automation and CI scenarios that need headless token auth (Notion's hosted MCP is OAuth-only)
  • Agents where context/token cost matters (only 422 tokens of tool schema at connection)
  • Workflows needing batch mutations, idempotency, retries, and rate limiting
  • Self-hosted deployments and developers exposing their own HTTP endpoint
  • Users of any MCP-speaking client (Claude, Cursor, VS Code, Cline, Zed, Continue, etc.)

Not for

  • Users who want a one-click Notion connection inside claude.ai or ChatGPT web UIs (use Notion's hosted MCP; ChatGPT's built-in connectors require OAuth-hosted servers)
  • Teams that prefer the official open-source server's one-tool-per-endpoint surface
  • Organizations unwilling to grant a third-party open-source service their Notion token (unless they audit or self-host)

Required permissions

  • Requires NOTION_TOKEN: a Notion Personal Access Token (ntn_…, recommended — scope equals your account, expires in ~1 year) or an Internal Integration secret (only pages explicitly Connected)
  • Optional NOTION_PAGE_ID as default parent for create_page / create_database
  • Optional NOTION_UPLOAD_ROOT to confine which local directory upload_file's path source can read
  • Optional read-only deployment via NOTION_READ_ONLY=true or NOTION_ALLOWED_OPERATIONS=read; fine-grained control via NOTION_ALLOWED_OPERATIONS / NOTION_BLOCKED_OPERATIONS with group presets

Risks and side effects

  • The token acts as you: a PAT sees everything you can see, so a leak equals workspace exposure — issue per-member tokens and revoke immediately if a device is lost
  • When binding a non-loopback HTTP host, anyone reaching /mcp acts as your NOTION_TOKEN; failing to set MCP_AUTH_TOKEN is a serious exposure
  • Without NOTION_UPLOAD_ROOT, an upload_file path source can read any file the server process can access
  • Many write ops can modify or remove content: blocking the destructive group does not disable parameter-based removals like update_database's in_trash — use READ_ONLY or allow=read for guaranteed no-mutation
  • HTTP mode is single-tenant with one shared token — unsuitable for multi-user sharing

Setup

Before you start

Runtime：Node.js · Docker

NOTION_TOKEN requiredsecret Notion Personal Access Token (ntn_...) or Internal Integration secret; create at app.notion.com/developers/tokens. Required.
MCP_AUTH_TOKEN optionalsecret Bearer token for HTTP mode; when set, every /mcp request must include an Authorization header.
Other optional settings (11)
NOTION_PAGE_ID optional Optional default parent page ID for create_page / create_database when no parent is passed.
NOTION_RATE_LIMIT optional Requests/second for the rate limiter, default 3.
NOTION_READ_ONLY optional Set to true/1/yes to disable every write operation.
NOTION_ALLOWED_OPERATIONS optional Comma-separated allowlist of operations or group presets (e.g. read).
NOTION_BLOCKED_OPERATIONS optional Comma-separated blocklist; wins over the allowlist.
NOTION_UPLOAD_ROOT optional Confines upload_file's path source to one directory so a model-composed path can't read arbitrary files.
HTTPS_PROXY optional HTTP(S) proxy for routing Notion API traffic on corporate networks.
HTTP_PROXY optional HTTP proxy env var; lowercase also accepted.
MCP_TRANSPORT optional Set to http to enable Streamable HTTP transport; default stdio.
PORT optional HTTP mode listen port, default 3000.
HOST optional HTTP mode bind address, default 127.0.0.1; set 0.0.0.0 only with MCP_AUTH_TOKEN.
  1. Create a Personal Access Token (ntn_…, recommended) at app.notion.com/developers/tokens, or an Internal Integration secret
  2. Claude Code: claude mcp add notion -s user -e NOTION_TOKEN=ntn_… -- npx -y notion-mcp-server; for Claude Desktop / Cursor add {"command":"npx","args":["-y","notion-mcp-server"],"env":{"NOTION_TOKEN":"…"}} to mcpServers config
  3. Claude Desktop alternatively supports a one-click .mcpb extension download
  4. Docker: docker run --rm -i -e NOTION_TOKEN ghcr.io/awkoy/notion-mcp-server:latest (-i required for stdio)
  5. Remote mode: start with MCP_TRANSPORT=http and always set MCP_AUTH_TOKEN when binding a non-loopback host.
.mcp.json 
{"mcpServers":{"notion":{"command":"npx","args":["-y","notion-mcp-server"],"env":{"NOTION_TOKEN":"ntn_paste_your_token_here"}}}}

Shown for Claude Code. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json
{
  "servers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "notion-mcp-server"
      ],
      "env": {
        "NOTION_TOKEN": "ntn_paste_your_token_here"
      }
    }
  }
}

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal
claude mcp add notion -e NOTION_TOKEN=ntn_paste_your_token_here -- npx -y notion-mcp-server

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

After restarting the client, type / in a new chat — notion_execute and notion_describe should appear in the tool list. Then ask the AI to create a test page via Notion; receiving a live page link confirms the connection works.

Troubleshooting

  1. object_not_found: an Internal Integration token was never Connected to the page — switch to a PAT or Connect the page
  2. Notion auth failed on every call: token missing, revoked, or expired (PATs expire after 1 year) — verify NOTION_TOKEN in client config
  3. No parent page configured: pass parent in the call or set NOTION_PAGE_ID
  4. multi_source_database from query_database: call list_data_sources and pass data_source_id instead
  5. Tools missing in Claude Desktop: token typo inside quotes, or the app wasn't fully quit (Cmd+Q) before reopening
  6. Docker exits immediately: add the -i flag for stdio; if NOTION_TOKEN isn't set, use -e NOTION_TOKEN (forwarding) or -e NOTION_TOKEN=ntn_xxx

Things to try

Once connected, you can ask your AI assistant things like:

  • Use Notion to make a page called 'Hello from my agent' and add a checklist of three things to try today.
  • Find every row in my Tasks database where Status is 'Doing' and tell me which are overdue.
  • Rename that page's title to 'Q3 plan'.
  • Comment on yesterday's meeting notes with a one-paragraph summary.

Tools 2

notion_execute writes
Runs any of 43 operations, singly or in batch mode; validation failures return schema, example, and a fix hint so the model self-corrects in one round-trip.
notion_describe read-only
Returns the JSON Schema and working example for one operation, useful before complex calls.

Use cases

Natural-language page creation, database querying, and block appends in Claude Desktop / Cursor
Batch-renaming 50 pages in one call (10-way parallel, idempotent retry)
Creating pages from Notion templates and filling in content
Full markdown round-trip editing (get_page_markdown → edit → update_page_markdown)
Headless Notion read/write in CI, cron jobs, or background agents
Querying a database via a view's stored filters with flattened rows
Uploading single- or multi-part files to pages

Supported clients

Claude Code
Claude Desktop
Cursor
VS Code
Cline
Zed
Continue
ChatGPTPartial support

Listed from the project's documentation, not tested by this site.

Overview

A third-party (awkoy) Notion Model Context Protocol server — not maintained by Notion. It authenticates with a token (Personal Access Token or Internal Integration secret), so it runs headless in CI, cron jobs, background agents, and self-hosted deployments where OAuth-only hosted MCP cannot. The server exposes exactly two MCP tools (notion_execute and notion_describe) that dispatch 43 operations across pages, blocks, databases, data sources, views, comments, users, and files, with operation schemas loaded on demand to keep the connection footprint small. It adds batched mutations with atomic rollback, idempotency keys, automatic rate-limit retry, full markdown round-trip, Notion templates, file uploads, flattened query rows, and access control via NOTION_READ_ONLY and operation allow/block lists. Beyond stdio it supports a Streamable HTTP transport (single-tenant, protectable with MCP_AUTH_TOKEN).

Similar servers

Compare with other MCP servers

Source revision 45447c9bfefe Data synced 2026-10-19 Read the FMRS scoring method