ConnectClaudeCodetoNotionwithMCP:ADeveloper'sGuide

📋 At a Glance

• Difficulty: Intermediate
• Time required: 30-45 minutes
• Prerequisites:
  • An active Notion account (free tier works)
  • Notion Internal Integration token (from Notion developer settings)
  • Claude Code installed and configured (claude CLI or Claude Desktop with MCP support)
  • Node.js 18+ installed
  • Basic familiarity with JSON and environment variables
• Works on: Windows 10/11, macOS (Intel/Apple Silicon), Linux

Why Connect Claude Code to Notion?

Connecting Claude to Notion transforms your workspace from a passive document store into an active AI-queryable knowledge graph. Claude Code's agentic loop can now pull context from your meeting notes before answering a question, write structured summaries back to a results database, or break down a Notion task into sub-tasks — without you switching tabs. For developers, this is especially powerful for maintaining living documentation, generating architecture decision records (ADRs) directly from conversations, and keeping project wikis up to date automatically.

The official Notion MCP server is maintained and versioned, which means it is far more stable than most community-built bridges and respects Notion's API rate limits out of the box.

How Do I Set Up the Notion MCP Server?

Setting up the Notion MCP involves installing Notion's official MCP server via npm and pointing Claude Code's MCP configuration to it. The server communicates with Notion's API using a secure Integration token you generate from your Notion developer dashboard.

1. Create a Notion Internal Integration

What: Generate an API token that allows programmatic access to your Notion workspace. Why: The MCP server authenticates all Notion API calls using this token. Without it, no requests to Notion can be made. An Internal Integration is scoped to only the pages you explicitly share with it, keeping your workspace secure. How:

1. Navigate to notion.so/my-integrations.
2. Click "New integration".
3. Give it a name (e.g., claude-mcp), select your workspace, and set type to Internal.
4. Under Capabilities, enable: Read content, Update content, Insert content.
5. Click Submit and copy the Internal Integration Secret (starts with secret_).

# Store your token securely — never hardcode it
export NOTION_API_KEY="secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Verify: > ✅ You have a token starting with secret_ copied to your clipboard. Test it with: curl -H "Authorization: Bearer $NOTION_API_KEY" -H "Notion-Version: 2022-06-28" https://api.notion.com/v1/users/me — you should see your bot user details.

2. Share Notion Pages with Your Integration

What: Grant the integration access to specific Notion pages and databases. Why: Notion's security model requires you to explicitly share each page with an integration. This is intentional — Claude will only see what you choose to expose, not your entire workspace. How:

1. Open any Notion page you want Claude to access.
2. Click the "..." (three-dot) menu in the top right.
3. Select "Connect to" and search for your integration name (claude-mcp).
4. Click Confirm. Repeat for all pages and databases you want accessible. Verify: > ✅ Run a test API call: curl -H "Authorization: Bearer $NOTION_API_KEY" -H "Notion-Version: 2022-06-28" https://api.notion.com/v1/search -d '{}' — the response should list your shared pages.

3. Install the Notion MCP Server

What: Install Notion's official MCP server package from npm. Why: This package handles the MCP protocol communication between Claude Code and the Notion API, including request formatting, pagination, and error handling. How:

# Install globally for easy CLI access
npm install -g @notionhq/notion-mcp-server

# Verify installation
notion-mcp-server --version

Verify: > ✅ You should see a version string like notion-mcp-server v1.x.x printed to your terminal. The command should be available globally in your PATH.

4. Configure Claude Code to Use the Notion MCP

What: Add the Notion MCP server to Claude Code's MCP configuration file. Why: Claude Code discovers available MCP servers through its configuration file. Without this entry, Claude has no knowledge of the Notion integration and cannot invoke it. How: Locate or create your Claude MCP config file:

• macOS/Linux: ~/.claude/mcp_servers.json
• Windows: %USERPROFILE%\.claude\mcp_servers.json

Add the following configuration:

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

⚠️ Replace the placeholder with your actual NOTION_API_KEY. For better security, reference an environment variable: "NOTION_API_KEY": "${NOTION_API_KEY}" and ensure the env var is set in your shell profile.

Verify: > ✅ Save the file and restart Claude Code. Run: claude mcp list — you should see notion listed as an active MCP server.

5. Test the Integration End-to-End

What: Send Claude a natural language command that requires fetching from or writing to Notion. Why: Confirms the full chain — Claude Code → MCP server → Notion API — is working correctly before you build workflows on top of it. How: Open Claude Code in your terminal and run:

claude

Then try:

List all pages in my Notion workspace that are shared with the claude-mcp integration.

Or:

Create a new page in my [Database Name] Notion database with the title "Test Entry" and a note saying "Created by Claude via MCP."

Verify: > ✅ Claude should return a list of pages or confirm the new page was created. Open Notion in your browser and verify the new entry exists in your database.

What Can I Build With Claude + Notion MCP?

Once connected, Claude Code can automate complex Notion workflows that previously required manual effort or expensive Zapier/Make integrations. Here are the highest-value use cases for developers:

1. Auto-generate Architecture Decision Records (ADRs)

What: Ask Claude to document a technical decision directly into a Notion ADR database. Why: ADRs are notoriously under-maintained because writing them is tedious. With MCP, Claude writes them for you based on your conversation. How:

We just decided to use Postgres instead of MongoDB for our new service because of
our team's SQL expertise and the need for strong ACID compliance. Write an ADR for
this decision and save it to my "Architecture Decisions" Notion database.

2. Daily Standup Summarizer

What: Claude reads your Notion task board and generates a standup summary. How:

Look at my "Sprint Board" Notion database, find all tasks assigned to me that 
are In Progress or blocked, and write a standup summary in this format:
- Yesterday: [completed tasks]
- Today: [in-progress tasks]
- Blockers: [blocked items]

3. Meeting Notes → Action Items

What: Paste meeting notes to Claude; it creates action items in your Notion task database. How:

Here are my meeting notes: [paste notes]. Extract all action items, assign 
due dates based on context, and add them to my "Tasks" Notion database with 
Status = "Not Started".

When Connecting Claude to Notion via MCP Is NOT the Right Choice

While the Notion MCP integration is powerful, there are scenarios where it is the wrong tool for the job.

1. Large-scale data migrations or bulk operations:

   • Limitation: Notion's API enforces rate limits (3 requests/second for free, higher for paid plans).
   • Why it's not suitable: Migrating thousands of records via Claude + MCP will be slow and may hit rate limits.
   • Alternative: Use Notion's official CSV import, or write a direct API script with proper rate-limit handling.

2. Real-time collaborative editing:

   • Limitation: MCP interactions are synchronous request/response. Claude cannot "watch" a page for live changes.
   • Why it's not suitable: If you need trigger-based automation (e.g., "when a task moves to Done, do X"), MCP polling is inefficient.
   • Alternative: Use Notion webhooks (beta) combined with a dedicated automation server.

3. Highly sensitive or private workspace data:

   • Limitation: All content Claude reads is sent to Anthropic's API for processing.
   • Why it's not suitable: If your Notion workspace contains proprietary code, unreleased product plans, or PII, you must evaluate your company's data privacy policy before granting Claude access.
   • Alternative: Use a self-hosted or private Claude deployment, or restrict integration access to non-sensitive pages only.

4. Complex relational database operations:

   • Limitation: Notion's relational database model (linked databases, rollups) does not always translate cleanly to API queries.
   • Why it's not suitable: Deeply nested relational queries may confuse Claude or return incomplete data.
   • Alternative: Export the data to a proper SQL database and use the Postgres MCP for complex querying.

#Frequently Asked Questions

Is the Notion MCP server official or community-built? Notion maintains an official MCP server at @notionhq/notion-mcp-server on npm. This is significant — it means the integration is actively maintained, respects Notion's API versioning, and is unlikely to break unexpectedly. It is still worth pinning to a specific version in production.

Will Claude read private pages in my Notion that I haven't shared with the integration? No. Notion's security model requires you to explicitly share each page or database with the integration using the "Connect to" flow. Pages not connected to your integration are completely invisible to the MCP server and therefore to Claude.

Can Claude write to Notion without me reviewing the content first? Yes — by default, Claude will execute write operations (creating or updating pages) without a confirmation step. If you are building automated workflows, add a review gate in your prompt: "Before creating this page, show me what you will write and ask for my approval."

#Quick Verification Checklist

• Notion Internal Integration created with Read, Update, and Insert capabilities.
• NOTION_API_KEY environment variable set securely in shell profile.
• Key Notion pages and databases shared with the integration via the "Connect to" menu.
• @notionhq/notion-mcp-server installed globally via npm and accessible in PATH.
• Claude Code's mcp_servers.json updated with the notion MCP server entry.
• claude mcp list shows notion as an active server.
• End-to-end test confirms Claude can list pages and create a test entry in Notion.
• Sensitive or private pages are NOT shared with the integration.

Related Reading

Last updated: April 18, 2026