← Back to directory

Notion MCP Server

Official

Official Notion MCP server for querying, editing, and managing Notion pages and databases via AI agents.

GitHub source repository ↗

★ 4.6k Stars Category · Collaboration Very popular Source revision 1d38420769c8

64FMRS · C

Reliability

8/20

Security and permissions

17/20

Maintenance

10/20

Documentation

16/20

Setup experience

13/20

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.

Read the FMRS scoring method →

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.

Tools

query-data-source

Query a data source (database) with filters and sorts.

retrieve-a-data-source

Get metadata and schema for a data source.

update-a-data-source

Update a data source's properties/schema.

create-a-data-source

Create a new data source under a database.

list-data-source-templates

List available page templates defined in a data source.

move-page

Move a page to a different parent page or database.

retrieve-a-database

Get database metadata, including the list of its data source IDs.

retrieve-page-markdown

Read a page's full content as Markdown, optionally inlining meeting-note transcripts.

update-page-markdown

Edit a page's content with Markdown, either replacing the whole page or making targeted find-and-replace edits.

Setup

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_****"}}}}

Generate and validate client config

Fit and risk

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

Troubleshooting

Confirm the target pages/databases are actually connected to the integration via the Access tab or 'Connect to integration'
Confirm the integration's Capabilities (e.g. write access) match the tools being called
Check that NOTION_TOKEN or OPENAPI_MCP_HEADERS is set correctly and hasn't expired in the client config
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
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
When using Streamable HTTP transport, verify the bearer token in requests matches the server's --auth-token/AUTH_TOKEN

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 DesktopFull support

CursorFull support

ZedFull support

GitHub Copilot CLIFull support

Related MCP servers

Compare with other MCP servers