Notion: Your Knowledge Base in Claude's Context

The spec that lives in Notion but never makes it into Claude's context

Most teams maintain their project documentation in Notion: architecture decision records, API specs, onboarding guides, product requirements documents. When a developer needs to implement something from those docs, the typical flow is to open Notion, find the right page, read it, copy the relevant sections, switch to Claude, and paste them in. If the spec is long, they summarize it themselves before pasting.

When Claude can read Notion directly, that process disappears. You ask Claude to read the spec and implement from it. Claude searches Notion, finds the page, reads the full content, and proceeds from the actual documentation rather than a human summary.

Two approaches to connecting Notion

Notion offers two ways to connect to Claude Code, with different authentication models and access scopes.

Option 1: Remote HTTP connector

If you use Claude Code with claude.ai authentication, you can connect Notion through the Anthropic Directory:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Then start a session and run /mcp to complete the OAuth flow. Alternatively, connect it through claude.ai → Settings → Connectors → Notion, and it will appear in Claude Code automatically on your next session.

This approach gives Claude access to your entire Notion workspace — every page and database your Notion account can see.

Option 2: stdio with an integration token

For more controlled access, use a Notion internal integration. Go to notion.so/my-integrations and create a new integration. Copy the Internal Integration Token (it starts with ntn_).

This token only grants access to pages and databases that you explicitly share with the integration. Open each Notion page you want Claude to access, click the three-dot menu, choose Connect to, and select your integration name.

Then add the server with the token:

claude mcp add --env NOTION_API_KEY=ntn_YOUR_TOKEN --transport stdio notion -- npx -y @modelcontextprotocol/server-notion

Or in your project .mcp.json using environment variable expansion:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-notion"],
      "env": { "NOTION_API_KEY": "${NOTION_API_KEY}" }
    }
  }
}

Set NOTION_API_KEY in your shell environment and Claude Code expands it at startup. This approach is safe to commit to version control because the actual token never appears in the file.

What Claude can do with Notion

With either connection method, Claude can:

• Search: Find pages by keyword across your entire accessible workspace
• Read pages: Retrieve the full content of any accessible page, including nested blocks
• Read databases: Query database rows with filters, sorts, and property values
• Create pages: Add new pages to a parent page or database
• Update properties: Change database properties like status, assignee, or date

A practical development workflow: keep your architecture decision records and API specifications in Notion. When you start implementing a feature, ask Claude to read the relevant ADR and proceed from the documented design. Claude reads the actual spec, not your recollection of it.

Search versus browse

When Claude searches Notion, it finds pages whose titles and content match a keyword. When it browses, it reads a specific page by ID or follows the workspace hierarchy. In practice, search is the faster path when you know a keyword from the document title. Use the page ID when you know exactly which document you need and want to avoid ambiguous search results.

For commonly referenced documents — your project README, your team's API style guide — consider adding the Notion page URL as a note in your CLAUDE.md so Claude can reference it directly without searching each time.