Notion MCP Server: Search & Edit Pages with AI

⏱️ 3 min read 🔌 MCP Server

What it is: Notion's official MCP server (@notionhq/notion-mcp-server), built on top of the same Notion API that powers third-party integrations. It gives an agent search, page/database reads, and page edits, authenticated through an internal integration token the way any other Notion API integration works.

Quick answer: Create an internal integration in Notion, share the specific pages or databases you want reachable with it, then run npx -y @notionhq/notion-mcp-server with the integration token supplied as a bearer credential. Notion's per-page sharing model is your main safety control — the integration (and the agent) can only see what's explicitly shared with it, nothing else in your workspace.

Why it matters for data work

A lot of "data" that matters day-to-day isn't in a database at all — it's a Notion doc: a metrics definition page, a launch tracker, a database of customer accounts someone built without SQL. An agent that can search and read Notion directly can pull the actual current definition of a metric instead of guessing, or update a status field on a tracker as part of a larger workflow.

Install & configure

Create an internal integration at notion.so/my-integrations, copy its token, then explicitly share each page or database you want it to access (the page's ··· menu → Connections). Nothing is visible to the integration until you do this, even with a valid token:

# Claude Code
claude mcp add notion -e NOTION_TOKEN=<integration-token> -- npx -y @notionhq/notion-mcp-server

// Claude Desktop / Cursor config
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": { "NOTION_TOKEN": "<integration-token>" }
    }
  }
}

Notion's docs have, in the past, documented auth via a header-bundling env var rather than a plain token — if NOTION_TOKEN alone doesn't authenticate, check the current setup guide on the repo for the exact variable name expected by the version you installed.

Which pages can the integration actually see?

This is the decision that matters most, and it's made per-page, not per-workspace. Sharing your entire workspace root with the integration effectively grants it everything underneath — convenient, but it means the agent can read (and, if you've enabled write capabilities, edit) far more than any single task needs. Share only the specific pages, databases, or a dedicated parent page for AI-accessible content, and add more as real needs come up rather than granting broad access up front.

How do I keep it safe?

Integration capabilities are also configured separately from sharing: when you create the integration, you choose whether it can read content, insert content, and update content — set only what you need. For anything beyond read-only exploration, remember Notion pages can contain content written by other people (comments, shared docs); an agent reading a page an outside collaborator edited is reading untrusted text, same as with any other data source.

Troubleshooting

Common snags with Notion's sharing model:

Search returns nothing: almost always a sharing issue — the integration hasn't been added as a connection on the page/database in question.
401 Unauthorized: the token is wrong, revoked, or belongs to a different workspace than the pages you're trying to reach.
Writes fail with a permissions error: the integration's capabilities are set to read-only — enable insert/update content capability in the integration's settings.
Tools missing after config change: restart the client fully; MCP config is read at launch.

Author & links

Author: Notion (official)

Repo: github.com/makenotion/notion-mcp-server

License: MIT

Related skills

For structured records instead of freeform docs, see the Airtable MCP server or Google Sheets MCP server. For team chat context, see the Slack MCP server.

← Back to MCP Servers