Notion MCP server setup for Claude Code and Cursor

Quick answer: The Notion MCP server is a Node process that exposes the Notion API as MCP tools. Install with one npx command, paste a Notion integration token into the env block, and your coding agent can read pages, query databases, and create content. Setup takes about 5 minutes, tested on server version 0.3.0 on April 15, 2026.

The Notion MCP server is a small Node process that speaks Model Context Protocol over stdio. Claude Code or Cursor launches it, passes a workspace integration token, and the model gets roughly 15 tool endpoints that map to the Notion REST API. Instead of telling the agent "here are the docs I pasted," you give it a page ID and it reads the live content.

This guide covers installation, editor configuration, working prompt patterns, and the friction points you will hit the first week.

What this server does

The server exposes Notion as a set of MCP tools. When Claude wants to read a page, it calls retrieve_page with a page ID. When it wants to add a row to a database, it calls create_database_item with a properties object. There is no ORM and no caching layer - each tool call hits the Notion REST API directly.

A non-exhaustive list of what the server can do:

• Retrieve pages by ID or URL
• Create new pages as children of a parent page or database
• Query databases with filter, sort, and cursor pagination
• Append blocks to any page, including toggles, callouts, and code blocks
• Update page properties like titles, select fields, and relations
• Search pages and databases by title
• List users in the workspace (with read-only scope)

Because the server runs as a local subprocess, your Notion token never touches the network outside of the API requests it makes. The token stays in memory for the life of the subprocess.

Installing Notion MCP

The package is published on npm as @notionhq/notion-mcp-server. The npx -y prefix fetches on first launch and caches for subsequent runs. First cold start pulls about 3.9 MB and takes 2 to 3 seconds.

Before you touch any config, create a Notion integration:

1. Open https://www.notion.so/my-integrations and click "New integration."
2. Name it something like "Claude Code MCP." Pick the workspace you want the agent to see.
3. Choose "Internal integration" - external is only needed for multi-tenant apps.
4. Copy the Internal Integration Secret. It starts with secret_.
5. Open the pages or databases you want the agent to reach, click the share menu, and invite the integration you just created. Notion will not let the server touch a page that has not been shared explicitly.

The share step trips up about half of first-time users. If the agent reports "object not found," check the share list on the page.

Configuring for Claude Code

Claude Code reads MCP servers from ~/.claude/mcp.json globally or .mcp.json in the project root. Add a notion entry with the token in the env block:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_API_KEY": "secret_your_key_here"
      }
    }
  }
}

Restart Claude Code. Run /mcp inside the session to confirm the server is attached. You should see around 15 tool names. Call search_pages with an empty query as a smoke test - if it returns the pages you shared with the integration, the wiring is correct.

For team use, drop a .mcp.json in the project root with a placeholder token and store the real one in a personal shell env var. Claude Code expands env vars in config at spawn time.

Configuring for Cursor

Cursor reads from ~/.cursor/mcp.json on macOS and Linux or the equivalent path on Windows. The JSON shape is identical:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_API_KEY": "secret_your_key_here"
      }
    }
  }
}

Open Cursor settings, navigate to the MCP tab, and toggle the server on. Cursor spawns the subprocess on the first tool call, paying a cold start cost of about 2 seconds. After that, typical request latency runs 300 to 600 ms depending on payload size.

Example prompts and workflows

Once the server is attached, Notion acts like another data source. A few prompts that work well:

• "Read the page at https://notion.so/acme/Architecture-123abc and summarize it in 5 bullet points."
• "Find every row in the Roadmap database where Status is In Progress and Owner is Alice."
• "Create a new page under the Meeting Notes parent with today's date and these action items."
• "Append a code block with this TypeScript snippet to the Design Notes page."
• "Search the workspace for pages mentioning rate limiting and list them with last-edited dates."

The model will chain tool calls automatically. A typical "summarize this page" flow runs retrieve_page then retrieve_block_children to get the body, which is 2 calls per page. Long pages with many child blocks may run 3 or 4 calls because of the pagination cursor.

One pattern that saves time: give the model the full page URL rather than asking it to search. Search is fuzzy and often returns 5 or 6 candidates the model then has to disambiguate. A direct URL skips that entirely.

Troubleshooting

Tool call returns object_not_found. The page or database was not shared with the integration. Open it in Notion, click share, and invite the integration by name.

Tool call returns unauthorized. The integration token is wrong or has been rotated. Regenerate in /my-integrations and restart the MCP server.

Rate limit errors (rate_limited). The Notion API allows about 3 requests per second per integration. When the agent chains many reads in a tight loop, you hit this. Ask the model to batch or space out calls, or create a second integration for read-heavy workflows.

Blocks nested more than 3 levels deep are truncated. The retrieve_block_children call returns up to 3 nested levels. For deeper trees, the model must call the endpoint again with each child's ID. This is a Notion API limit, not an MCP server limit.

Server fails to start with ENOENT. npx is not on PATH in the env Claude Code or Cursor inherits. Launch the editor from a shell session or put the absolute path to npx in the config.

Alternatives

If the Notion server does not fit, a few options exist:

• obsidian-mcp targets Obsidian vaults over the local filesystem. Faster than any cloud API and works offline.
• confluence-mcp is the Atlassian equivalent if your team lives in Confluence instead of Notion.
• mcp-server-filesystem with an exported Notion workspace as markdown is useful for bulk analysis without rate limits.

For read-only workflows with thousands of pages, the filesystem approach wins on speed. For active edits, the Notion server is the right default.

The Notion MCP server is worth keeping attached if you live in Notion day to day. Five minutes of setup plus one share step per page replaces an hour of copy-paste per week.