Problem: Claude Can't Read Your Notion Docs

MCP Notion Server bridges the gap between your Notion workspace and AI tools like Claude and Cursor — but the setup has a few sharp edges that trip up most developers on the first attempt.

If you've tried to point Claude at your Notion knowledge base and gotten nothing but a blank stare, you're not alone. The Model Context Protocol (MCP) is the standard way to give LLMs real-time access to external data sources, and Notion is one of the most valuable sources a developer can unlock.

You'll learn:

How to create a Notion integration and scope it correctly
How to configure notion-mcp-server for Claude Desktop and Cursor
How to verify Claude can actually query your pages and databases

Time: 15 min | Difficulty: Intermediate

Why This Happens

MCP servers act as a translation layer — they expose tools that an LLM can call to read (and optionally write) external data. Without one, Claude has no mechanism to fetch live content from Notion, even if you paste in the URL.

The Notion MCP server wraps the official Notion API and exposes it as a set of MCP tools: search, retrieve_page, query_database, and a handful of others. When Claude needs context from your docs, it calls these tools at inference time instead of relying on stale training data.

Common symptoms without MCP:

Claude says "I don't have access to your Notion workspace"
Pasting Notion URLs into Claude returns generic summaries, not real content
Cursor Agent can't find internal documentation when writing code

Solution

Step 1: Create a Notion Integration

Go to https://www.notion.so/my-integrations and click New integration.

Name: mcp-ai-access (or anything descriptive)
Capabilities: Check Read content. Only add Update/Insert if you want Claude to write back to Notion.
Associated workspace: Pick your target workspace

Click Submit and copy the Internal Integration Token — it looks like secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. This is your NOTION_API_KEY.

Critical: Notion uses a permission model where integrations only see pages you explicitly share with them. After creating the integration, open every page or database you want Claude to access and click Connect to → select your integration. If you skip this step, queries return empty results.

Step 2: Install notion-mcp-server

# Requires Node 20+ — verify first
node --version

# Install globally
npm install -g notion-mcp-server

# Confirm the binary is available
notion-mcp-server --version

Expected output:

notion-mcp-server/1.x.x node/v22.x.x

If it fails:

command not found → Your npm global bin isn't on $PATH. Run npm bin -g and add that directory to your shell profile.
ERR_UNSUPPORTED_NODE_VERSION → Upgrade to Node 20+: nvm install 22 && nvm use 22

Step 3: Configure Claude Desktop

Open your Claude Desktop config file:

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
nano ~/.config/Claude/claude_desktop_config.json

# Windows (PowerShell)
notepad "$env:APPDATA\Claude\claude_desktop_config.json"

Add the Notion server block inside mcpServers:

{
  "mcpServers": {
    "notion": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_API_KEY": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Save the file and fully quit and relaunch Claude Desktop. The MCP server won't load from a window refresh — it requires a full restart.

Expected: After relaunch, open a new conversation. You should see a hammer icon (🔨) in the input bar indicating active MCP tools.

Step 4: Configure Cursor (Optional)

If you use Cursor alongside Claude Desktop, add the same server to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "notion": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_API_KEY": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

For a global Cursor config that applies across all projects, put the file at ~/.cursor/mcp.json instead.

Restart Cursor and open the Chat panel. In Agent mode, Cursor will now call Notion tools automatically when you ask questions about your documentation.

Step 5: Scope What the Server Can Access (Optional but Recommended)

By default, notion-mcp-server exposes all pages your integration can reach. For large workspaces, this creates noise — Claude will sometimes search broadly when a narrow query would serve better.

You can restrict access by only sharing specific databases with the integration (back in Notion's Connect to settings), or by passing a NOTION_PAGE_ID environment variable to pin the server to a root page:

{
  "mcpServers": {
    "notion": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_API_KEY": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "NOTION_PAGE_ID": "your-root-page-id-here"
      }
    }
  }
}

Find a page ID in the Notion URL: https://notion.so/Your-Page-Title-{PAGE_ID} — the 32-character hex string at the end.

Verification

In Claude Desktop, open a new conversation and ask:

Search my Notion workspace for [topic you know exists in your docs]

You should see: Claude calling the search tool, then returning real content from your pages — not a hallucinated summary.

Test database queries specifically:

List all items in my [database name] Notion database where status is "In Progress"

You should see: Claude calling query_database and returning filtered rows.

If Claude responds without calling any tools, the MCP server didn't load. Re-check the config file path and restart Claude Desktop completely (quit from the menu bar, not just close the window).

What You Learned

Notion MCP requires explicit page/database sharing — the integration token alone isn't enough
NOTION_PAGE_ID scoping prevents Claude from over-searching large workspaces
The same server config works for both Claude Desktop and Cursor with no modification

Limitation: The Notion API has a rate limit of 3 requests/second. For large-scale agent workflows querying many pages in parallel, you'll hit 429 errors. Add NOTION_RATE_LIMIT_DELAY=400 to your env config to throttle requests automatically.

Tested on notion-mcp-server 1.3.x, Node 22.x, Claude Desktop 0.9.x, macOS Sonoma and Ubuntu 24.04

FAQ

Q: How do I connect Claude to Notion without installing anything globally? A: Use npx instead of a global install. Replace "command": "notion-mcp-server" with "command": "npx" and add "args": ["-y", "notion-mcp-server"] to your config. This runs the package on demand without a global install.

Q: What is the difference between notion-mcp-server and the Notion API directly? A: The Notion API requires you to write code to call it. notion-mcp-server wraps the API as MCP tools so Claude can call it autonomously — no custom integration code required on your end.

Q: Does this work on Windows without WSL? A: Yes. Use PowerShell to set $env:NOTION_API_KEY if testing manually, and use the JSON config path under %APPDATA%\Claude\ for the persistent config. Node 22 on Windows is fully supported.

Q: Can Claude write back to Notion, not just read? A: Yes, but only if you enabled Insert content and Update content capabilities when creating the integration. By default, read-only is safer. Add write capabilities in your integration settings at notion.so/my-integrations if needed.