Notion

Notion MCP server

Search, read and write your Notion workspaces from your AI assistant, several through one server: pages as Markdown, databases queried and counted by column, saved views, people, comments and files. It creates pages, rows, columns and databases, edits properties and bodies, comments, uploads files, and moves pages to Notion's trash (kept 30 days; restore_page brings them back). No tool is money.

You need a Notion integration per workspace, its token in a file of its own, and your top-level pages shared with it: an integration sees only what you share. Uploads take files up to 20 MiB (5 MiB on Notion's Free plan).

What you can ask

• "Find the Q3 roadmap page in my work workspace and summarise it."
• "How many rows of the Tasks database are in each Status?"
• "Show me my Due this week view."
• "Add 'Thinking in Systems' to the Reading List with status To read and the tag Books."
• "In the Onboarding page, replace 'Slack' with 'Mattermost' everywhere."
• "Download the PDFs attached to the Client SRL row of the Contracts database."

Install

With Claude Code:

claude mcp add notion -e NOTION_TOKENS_DIR="<path to Notion tokens folder>" -- npx -y @foreverworks/mcp-notion

Claude Desktop (Settings, Developer, Edit Config) and most other clients read the same command as JSON:

{

"mcpServers": { "notion": { "command": "npx", "args": ["-y", "@foreverworks/mcp-notion"], "env": { "NOTION_TOKENS_DIR": " " } } } }

Each runs the published package on Node 22.19 or newer. VS Code and the Claude Desktop bundle ask for NOTION_TOKENS_DIR as they add the server. Cursor reads it from your environment instead (${env:NOTION_TOKENS_DIR}), so set it before you start Cursor. Configuration says what it holds.

From a clone

git clone https://github.com/foreverworks/mcps.git && cd mcps

npm ci && npm run build claude mcp add notion -e NOTION_TOKENS_DIR=" " -- node "$PWD/servers/notion/dist/index.js"

In a JSON configuration, the command is node and its one argument the full path of servers/notion/dist/index.js. To share one running copy between several clients over HTTP, see docs/deploying.md.

Over HTTP, a deployment that limits its hosts sets MCP_EGRESS_ALLOW=api.notion.com,prod-files-secure.s3.us-west-2.amazonaws.com,s3.us-west-2.amazonaws.com: Notion's API and the hosts its files are served from.

Configuration

Each file is a workspace: notion-personal and notion-work are labelled personal and work, and the server names the labels it found at start. A label is lower-case letters, digits and hyphens; an empty file is skipped. There is no default folder, so a test or a hand-run copy cannot reach a workspace by accident. The files are re-read at most once a minute, and at once after a refused token, so a new token needs no restart. The variables every server shares (transport, limits, MCP_FILE_ROOTS for uploads) are in docs/configuration.md.

Getting a token

For each workspace:

1. Open https://www.notion.so/profile/integrations, signed in to that workspace, and create a new internal integration.
2. Turn on the capabilities the assistant needs: read, update and insert content for pages and databases, and the comment capabilities for comments. People's emails appear only if it may read user information with email addresses.
3. Copy its Internal Integration Secret straight into notion- in your tokens folder, readable by you alone (mode 0600). Do not paste it into a chat.
4. Share your pages with the integration, which starts out seeing nothing. In Notion, open each top-level page the assistant should reach, then the ••• menu, Connections, and add the integration. Pages under it inherit the access; a new top-level page must be shared the same way.

A personal access token works in the same file instead (made at https://www.notion.so/developers/tokens, signed in to the workspace, with the Notion API capability). It acts as you: it sees every page you see, with nothing to share, and can create private top-level pages, which an integration cannot. It expires within a year.

First run

Ask your assistant to run Notion's health check. Per workspace, it says whether the token is accepted, the workspace and integration names, and whether the integration sees any page yet; if not, do step 4 above.

From a shell, node dist/index.js --health prints one NOTION: line per workspace and exits 0 when all is well, 1 when a person has to act (a refused token, a missing capability), and 2 for a warning (an integration that sees nothing yet, or Notion unwell), which suits a timer.

Tools

read changes nothing; write changes something in a workspace. A tool that takes an id also takes a Notion URL, and finds the workspace itself.

Workspaces and search

Pages

Databases

Comments and files

test/tools.snapshot.json pins what a client lists; a diff there is a breaking change.

Troubleshooting

`health` says "the integration sees no page yet", or a call answers `not_shared`. Notion answers the same 404 for an id that does not exist and a page not shared with the integration. Check the id, then share the page (step 4 of Getting a token); sharing a top-level page shares everything under it.

`auth`. The token was refused: revoked, or a personal access token past its expiry. Put a new one in the notion- file; the next call reads it.

`forbidden`. The integration lacks a capability for this call. Turn it on at https://www.notion.so/profile/integrations (step 2 of Getting a token).

`config`. No token files where NOTION_TOKENS_DIR points, an unreadable one, or one holding more than one token. For download_files, set NOTION_OUTBOX_DIR.

`input` from `create_page` with no parent. Notion refuses a top-level page from an integration; give a parent page, or use a personal access token. Any other input names what to fix, and nothing changed.

`outcome_unknown`. An append, a find-and-replace, a new page or a comment lost its answer; it is never resent blind. Read the page (or search for a new one) before writing again: the change may be there.

`conflict`: someone edited the same object at that moment; read it again, then retry. `rate_limited`: Notion still throttles after the retries (180 requests a minute on the Free plan); wait a minute. `api`: Notion was unreachabl