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

Notion MCP Server

Official
Official Notion MCP server for querying, editing, and managing Notion pages and databases via AI agents.
How to install ↓ Compare GitHub source repository ↗
Category
Collaboration #2 of 55
Stars
★ 4.7k Very popular
Transport
stdio (local process) · Streamable HTTP
Runtime
Node.js · Docker
Credentials
API key / credential required
License
MIT
Last commit
Tools
9
64FMRS · C

This is Notion's official, open-source local MCP server, covering pages, databases/data sources, comments, and token-efficient Markdown page editing, with documentation kept current through API changes like the v2.0.0 data-source migration. However, Notion explicitly directs active support toward its newer remote, OAuth-based Notion MCP server and flags this repository as a candidate for future sunset with unmonitored issues/PRs, which should factor into any long-term adoption decision.

Strongest · Security and permissions 17/20 Weakest · Reliability 8/20

Reliability
8/20
Security and permissions
17/20
Maintenance
10/20
Documentation
16/20
Setup experience
13/20
Why each score
Reliability 8/20
The README gives specific, plausible details (tool count moving from 19 to 22, API version migration from 2025-09-03 to 2026-03-11) and references `npm run build` / `npm test`, implying build/test scripts exist. However, no CI workflow files or actual test contents were presented in this review, so the MCP init/tool-list handshake cannot be verified as reproducible. Per the static calibration rule, without verifiable execution evidence (real CI plus committed tests covering key paths), reliability is capped at 12, and given the total absence of that evidence here, a lower-mid score is warranted.
Security and permissions 17/20
The server shows notable security awareness: it recommends configuring a least-privilege (read-only) Notion integration and explicitly states database deletion is not possible via MCP; the HTTP transport requires bearer-token auth by default, and disabling it requires an explicit `--unsafe-disable-auth` flag with an accompanying warning; DNS-rebinding protection (Host/Origin header checks) is enabled even when auth is disabled; the multi-tenant token-passthrough feature validates token prefixes, binds tokens per session, redacts them from logs, and recommends TLS. No plaintext credentials appear in examples (all placeholders like `ntn_****`), and there are no unconfirmed irreversible dangerous defaults, so no red line is triggered. Points are withheld because least-privilege scoping is opt-in rather than default, and there is no disclosure about Notion-side data retention/encryption.
Maintenance 10/20
The repository belongs to Notion's official GitHub organization, is MIT licensed, and shows genuine recent development (v2.0.0 API migration, new Markdown tools targeting the 2026-03-11 API version), indicating active code evolution. However, the README explicitly states the local server may be sunset and that 'Issues and pull requests here are not actively monitored' — an explicit, official statement of reduced community support and possible future deprecation. This is a clear governance/support weakening signal that must be substantially penalized, placing the score in the 'active but with clear governance gaps' range rather than higher.
Documentation 16/20
The README is extensive, covering multi-client installation (Cursor, Claude Desktop, Zed, Copilot CLI), both npm and Docker execution paths, both STDIO and HTTP transport modes, three authentication configuration options, detailed token-passthrough semantics with examples, and a migration table for the breaking v2.0.0 changes — all reviewable evidence. Gaps: it does not enumerate parameters/limits for all 22 tools individually, lacks a dedicated troubleshooting section, and does not disclose rate limits or usage costs, so it falls short of a perfect score.
Setup experience 13/20
Setup is clearly documented with both npm/npx and Docker (official image and local build) options plus example configs for several mainstream clients, including screenshots for the Notion-side integration steps. It still requires manual steps — creating a Notion integration, connecting pages/databases individually, and configuring environment variables or headers correctly — making it usable but somewhat manual and fragile. Per the static calibration rule, without verifiable execution evidence, setup cannot exceed 15, so a mid-range score within that ceiling is given.

Static review · not runListed 2026-08-26

Read the FMRS scoring method →

Fit and risk

What it can accessUses the networkChanges third-party account data

Best for

  • Teams and individuals who already manage docs/wikis in Notion and want AI clients (Claude Desktop, Cursor, etc.) to operate on that content directly
  • Developers who want to self-host a local MCP server rather than use a remote hosted option
  • Automation/agent workflows that need to query or update Notion database records programmatically

Not for

  • Users who want the standard-OAuth, zero-JSON-config install with active official support — Notion recommends its newer remote Notion MCP server for that
  • Users uncomfortable handing a Notion integration token to a locally-run LLM client
  • Use cases needing capabilities the integration deliberately excludes, such as deleting databases
  • Long-term production deployments that need guaranteed maintenance, given this repo may be sunset

Required permissions

  • A Notion internal integration token (NOTION_TOKEN or the Authorization value in OPENAPI_MCP_HEADERS), scoped by that integration's Capabilities (can be limited to read-only)
  • Access limited to the specific pages/databases explicitly connected to the integration, not the whole workspace
  • A separate bearer auth token when using the Streamable HTTP transport (--auth-token / AUTH_TOKEN)
  • Network access to the Notion API

Risks and side effects

  • If the integration is granted broad read/write capabilities and connected to many pages, that content is effectively exposed to the LLM, risking data leakage or unintended edits
  • Running with --unsafe-disable-auth removes bearer authentication on the HTTP transport, potentially making it reachable via DNS rebinding from pages a user visits — the README says to only use it on an isolated network
  • Multi-tenant token passthrough requires careful TLS/gateway configuration; misconfiguration risks leaking or misrouting Notion tokens between tenants
  • The README states this local server may be sunset in favor of the remote Notion MCP, and that issues/PRs here are not actively monitored, so long-term maintenance and security fixes are not guaranteed
  • Storing NOTION_TOKEN or OPENAPI_MCP_HEADERS directly in shared client config files risks leaking the secret

Setup

Before you start

Runtime：Node.js · Docker

NOTION_TOKEN requiredsecret Notion internal integration secret (ntn_ prefix), obtained from the Configuration tab at notion.so/profile/integrations.
OPENAPI_MCP_HEADERS optionalsecret Advanced alternative to NOTION_TOKEN: a JSON string with Authorization and Notion-Version headers.
AUTH_TOKEN optionalsecret Bearer token for the server's own HTTP auth in Streamable HTTP transport mode; you choose the value.
Other optional settings (1)
ENABLE_TOKEN_PASSTHROUGH optional Set to true to enable per-request Notion token passthrough for multi-integration deployments; not a secret.
  1. Create an internal Notion integration at notion.so/profile/integrations and copy its token (starts with ntn_); optionally restrict its Capabilities (e.g. read-only) to limit risk.
  2. Connect the pages/databases you want exposed to that integration, via the integration's Access tab or by using 'Connect to integration' on individual pages.
  3. Add an MCP server entry to your client's config (Claude Desktop, Cursor, Zed, GitHub Copilot CLI, etc.) running the server via npx or Docker, setting the NOTION_TOKEN (or OPENAPI_MCP_HEADERS) environment variable.
  4. Optionally run with --transport http instead of the default stdio, providing an auth token via --auth-token or AUTH_TOKEN; for multi-tenant deployments enable --enable-token-passthrough so each client supplies its own Notion token via the Notion-Token header on initialize.
claude_desktop_config.json 
{"mcpServers":{"notionApi":{"command":"npx","args":["-y","@notionhq/notion-mcp-server"],"env":{"NOTION_TOKEN":"ntn_****"}}}}

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

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

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

Terminal
claude mcp add notionApi -e 'NOTION_TOKEN=ntn_****' -- npx -y @notionhq/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 connecting, check the client's tool list for tools like query-data-source and retrieve-page-markdown; then prompt "Get the content of page <page_id>" — a returned Notion page confirms the connection works.

Troubleshooting

  1. Confirm the target pages/databases are actually connected to the integration via the Access tab or 'Connect to integration'
  2. Confirm the integration's Capabilities (e.g. write access) match the tools being called
  3. Check that NOTION_TOKEN or OPENAPI_MCP_HEADERS is set correctly and hasn't expired in the client config
  4. After upgrading to v2.0.0, update any hardcoded references to the removed database tools or the database_id parameter to the new data-source tools and data_source_id
  5. If the Markdown tools (retrieve-page-markdown / update-page-markdown) error out, check whether a custom Notion-Version set via OPENAPI_MCP_HEADERS is overriding the required 2026-03-11 version
  6. When using Streamable HTTP transport, verify the bearer token in requests matches the server's --auth-token/AUTH_TOKEN

Things to try

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

  • Comment "Hello MCP" on page "Getting started"
  • Add a page titled "Notion MCP" to page "Development"
  • Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2
  • Query my data source for all entries with status To-do

Tools 9

query-data-source read-only
Query a data source (database) with filters and sorts.
retrieve-a-data-source read-only
Get metadata and schema for a data source.
update-a-data-source writes
Update a data source's properties/schema.
create-a-data-source writes
Create a new data source under a database.
list-data-source-templates read-only
List available page templates defined in a data source.
move-page writes
Move a page to a different parent page or database.
retrieve-a-database read-only
Get database metadata, including the list of its data source IDs.
retrieve-page-markdown read-only
Read a page's full content as Markdown, optionally inlining meeting-note transcripts.
Show 1 more tools
update-page-markdown writes
Edit a page's content with Markdown, either replacing the whole page or making targeted find-and-replace edits.

Use cases

Let an AI assistant search, read, and edit Notion page content
Have an AI agent query, filter, and update records in a Notion database (data source)
Add comments to pages or create new sub-pages from natural-language instructions
Read and rewrite whole pages as Markdown for token-efficient bulk edits

Supported clients

Claude Desktop
Cursor
Zed
GitHub Copilot CLI

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

Overview

This repository is Notion's officially maintained local MCP server that wraps the Notion API, communicating with clients over stdio or Streamable HTTP. It exposes tools for search, page creation, comments, and querying/updating databases (as 'data sources'), plus newer tools for reading and editing whole pages as Markdown (requiring Notion API version 2026-03-11), which is significantly more token-efficient than raw block JSON. The README notes that Notion has released a separate, remote, OAuth-based 'Notion MCP' server that it now prioritizes and actively supports; this local server may be sunset in the future and its issues/PRs are not actively monitored. Version 2.0.0 migrates to Notion API 2025-09-03, replacing the old database-query/update/create tools with data-source equivalents and switching parameters from database_id to data_source_id.

Similar servers

Compare with other MCP servers

Source revision 730ae781ba28 Data synced 2026-10-13 Read the FMRS scoring method