Notion MCP Server (official)
OfficialOfficial Notion server to read, search, create, and update pages and databases in your workspace.
Add to your client
Copy the config for your MCP client and paste it into its config file.
npx -y @notionhq/notion-mcp-serverPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"notion-mcp-server-official": {
"command": "npx",
"args": [
"-y",
"@notionhq/notion-mcp-server"
],
"env": {
"NOTION_TOKEN": "<your-notion-integration-token>"
}
}
}
}Before you start
- Node.js (a current LTS, Node 18+; run via npx without a global install)
- A Notion internal integration token (an 'Internal Integration Secret') created at https://www.notion.so/profile/integrations
- Each page/database the agent should touch must be shared with the integration (via the page's Connections menu or the integration's Access tab)
- Optional: Docker if you prefer the mcp/notion image instead of npx
About Notion MCP Server (official)
This is Notion's official MCP server, letting an AI agent read, search, create, and update content in your Notion workspace — pages, databases (data sources), blocks, and comments — through the Notion API. It wraps Notion's REST endpoints as MCP tools so an agent can answer questions from your docs or write structured changes back.
The repo (@notionhq/notion-mcp-server) runs locally over stdio or streamable HTTP, authenticated with a Notion internal integration token. A key gotcha: the integration only sees pages and databases you've explicitly shared with it, so you must connect target pages to the integration before tools return anything.
Notion now also offers a hosted remote MCP server (mcp.notion.com) with one-click OAuth setup and more token-efficient, Notion-tuned tools. Notion has signaled it is prioritizing the remote server and may sunset active support for this local repo, so for new setups the hosted OAuth option is often the simplest path; the local package remains useful for self-hosted/stdio scenarios and fine-grained control.
Tools & capabilities (9)
searchSearch across pages and databases in the workspace
retrieve-a-page / create-a-page / update-a-page / move-pageRead, create, update, and move pages
query-data-sourceQuery a database/data source with filters and sorts
retrieve-a-data-source / create-a-data-source / update-a-data-sourceRead and manage database (data source) schemas
retrieve-a-databaseRetrieve a database object
append-block-children / retrieve-block-childrenRead and append child blocks within a page
update-block / delete-a-blockEdit or delete individual content blocks
retrieve-comments / create-a-comment / update-a-comment / delete-a-commentRead and manage page comments
list-data-source-templatesList templates available for a data source
When to use it
- Use it when you want an agent to answer questions from your Notion docs and wikis
- Use it when you want to create or update Notion pages (meeting notes, specs, tickets) from chat
- Use it when you need to query a Notion database with filters/sorts and act on the results
- Use it when syncing or appending structured content into a Notion knowledge base
- Use it when leaving or reading comments on Notion pages as part of a workflow
- Use it when building an agent that turns conversation into organized Notion records
Quick setup
- 1Create an internal integration at notion.so/profile/integrations and copy its secret token
- 2Share the specific pages/databases with the integration (Connections menu on the page or the integration's Access tab)
- 3Add the server to your MCP client, e.g. run `npx -y @notionhq/notion-mcp-server` with NOTION_TOKEN set to your secret
- 4Restart your MCP client so it loads the server
- 5Verify by asking the agent to search your workspace or retrieve a known page
- 6Alternatively, connect the hosted remote server at mcp.notion.com via OAuth for a no-token setup
Security notes
The integration token grants API access only to pages and databases you explicitly share with it, so scope access narrowly. Store NOTION_TOKEN as an env var, never in committed config.
Notion MCP Server (official) FAQ
Why do the tools return nothing / 'object not found'?
The integration can only see pages and databases explicitly shared with it. Open the target page's Connections menu (or the integration's Access tab) and add the integration.
How do I provide the token?
Set the NOTION_TOKEN environment variable to your integration's internal secret (recommended). An advanced OPENAPI_MCP_HEADERS variable also exists for passing custom Authorization and Notion-Version headers.
Is there a hosted/remote version?
Yes. Notion offers a remote MCP server at mcp.notion.com with OAuth-based setup and Notion-optimized tools; Notion is prioritizing it and may reduce support for this local repo.
Does it support HTTP transport?
Yes — besides the default stdio transport, it can run as a streamable HTTP server with bearer-token auth on a configurable port.
Is it official and free?
It's maintained by Notion (makenotion) under the MIT license and is free to run; you only need a free Notion integration token.
Alternatives to Notion MCP Server (official)
Self-hosted MCP server for Jira and Confluence Cloud and Server/Data Center.
Read, search, and edit your Obsidian vault through the Local REST API community plugin.
Linear's official hosted MCP server — find, create, and update issues, projects, and comments.
Compare Notion MCP Server (official) with: