DEV Community

mibii
mibii

Posted on

Claude Code + Notion: Full Workflow From Zero to Automated Knowledge System

#claudecode #notion #productivity #mcp

Obsidian vs Notion: If you read the Obsidian version of this guide, here's the key difference upfront. Obsidian stores plain Markdown files — Claude Code reads them directly, zero setup. Notion stores everything in a proprietary database — you need MCP to bridge them. That adds 15 minutes of setup. The payoff is real-time sync and team collaboration that Obsidian can't match.

Why Connect Them at All

When you work in Claude Code, your Notion workspace is invisible. Every time you need context from a spec, a meeting note, or a project page — you're copying and pasting between tabs.

With Notion MCP connected, Claude Code can:

  • Search your entire workspace from the terminal
  • Pull a PRD or spec directly into a coding session
  • Create and update pages without leaving your terminal
  • Sync documents you drafted locally to Notion for team review
  • Query databases in plain English ("show me all open tasks due this week")

The workflow becomes: draft in Claude Code → push to Notion when you need collaboration → pull feedback back when you're ready to continue.

No copy-paste. No version confusion. The two stay in sync.

Part 1: Install Everything

Step 1 — Install Claude Code 

# macOS
brew install --cask claude-code

# Windows
winget install Anthropic.ClaudeCode

# Linux
curl -fsSL https://claude.ai/install.sh | bash

# Verify
claude doctor
claude auth login
Enter fullscreen mode Exit fullscreen mode

Requirements: Claude Pro ($20/mo) or Max subscription.

⚠️ npm install -g @anthropic-ai/claude-code is deprecated. Use the native installer.

Step 2 — Have a Notion Account

If you don't have one: notion.so. Free plan works for personal use. For team collaboration, you'll need Plus or higher.

Part 2: Connect Notion to Claude Code

Unlike Obsidian (plain files), Notion requires an authenticated connection through MCP. Two methods — pick one.

Method A — Official Plugin (Recommended, 5 minutes)

Notion built and maintains an official Claude Code plugin that installs everything in one command: MCP server + Skills + slash commands.

claude plugin add makenotion/claude-code-notion-plugin
Enter fullscreen mode Exit fullscreen mode

Then authenticate:

claude
> /mcp
Enter fullscreen mode Exit fullscreen mode

Claude will prompt you to complete an OAuth flow in your browser. Log in with your Notion account, authorize access, done.

Verify the connection:

> "List a random page title from my Notion workspace"
Enter fullscreen mode Exit fullscreen mode

If it returns real content — you're connected.

Method B — Manual MCP Setup (More Control)

Add Notion's hosted MCP server directly:

claude mcp add --transport http notion https://mcp.notion.com/mcp
Enter fullscreen mode Exit fullscreen mode

Start a session and complete OAuth:

cd your-project
claude
Enter fullscreen mode Exit fullscreen mode

Claude will detect the server and prompt for authentication on first Notion tool use.

Verify:

claude mcp list
# Should show: notion  https://mcp.notion.com/mcp  connected
Enter fullscreen mode Exit fullscreen mode

Share with Your Team

Add to .mcp.json in your project root (commit this):

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Each team member authenticates with their own Notion account. Claude respects individual permissions — it can only access what each person can access.

⚠️ Important: Notion MCP uses OAuth — it acts with your full Notion permissions. Claude can access everything you can access. Be intentional about what you ask it to do.

Part 3: What Notion MCP Can Actually Do

Once connected, Claude Code gets these tools:

Tool What it does
notion-search Full-text search across your workspace
notion-fetch Read a specific page by URL or ID
notion-create-pages Create new pages in any location
notion-update-page Edit existing page content
notion-query-database Query a Notion database with filters
notion-add-comment Post comments on pages
notion-list-users List workspace members

Notion's hosted MCP server converts everything to Markdown before sending to Claude — optimized for AI consumption, not the raw JSON block format from the original API. This matters: it's significantly more token-efficient.

Part 4: CLAUDE.md for Notion Workflows

Tell Claude about your Notion structure so it doesn't have to guess.

# Project Context

## Notion Workspace Structure
- **Engineering** — technical specs, ADRs, runbooks
  - Specs database: [your-database-url]
  - ADR database: [your-database-url]
- **Product** — PRDs, roadmap, research
  - PRD database: [your-database-url]
- **Meetings** — all meeting notes, searchable by date and project
- **Tasks** — sprint board and backlog

## Document Conventions
- PRDs have properties: Status (Draft/Review/Approved), Owner, Sprint
- ADRs follow format: Context → Decision → Consequences
- Meeting notes always include: Date, Attendees, Decisions, Action Items

## What Claude Can Do Here
- Search Notion for context before starting any implementation task
- Pull specs into coding sessions without me copy-pasting
- Create draft docs in Notion from local files when review is needed
- Update task status in the sprint board after completing work
- Query the meetings database to find decisions on any topic

## What Claude Should NOT Do
- Never delete Notion pages — archive them instead
- Don't update pages in the Product space without checking with me
- Always show me what it plans to create before creating it
Enter fullscreen mode Exit fullscreen mode

Part 5: Core Workflows

Workflow 1 — Pull Context Before Coding

You're about to implement a feature. Instead of digging through Notion manually:

> "Find the spec for the authentication refactor and summarize what I need to implement"
Enter fullscreen mode Exit fullscreen mode

Claude searches your workspace, finds the PRD, reads it, and gives you a focused summary. You can then say:

> "Now implement the JWT refresh token logic based on that spec"
Enter fullscreen mode Exit fullscreen mode

Claude codes with full spec context — no copy-paste required.

Workflow 2 — Push Docs for Team Review

You drafted a technical spec locally in Markdown. Time to get team feedback.

Create .claude/commands/push-to-notion.md:

---
description: Push a local document to Notion for collaboration
allowed-tools: Bash, Glob, Read, mcp__notion__notion-create-pages,
  mcp__notion__notion-search, mcp__notion__notion-fetch,
  mcp__notion__notion-update-page, AskUserQuestion
---

# Push to Notion

Push a local document to Notion. Only syncs changes — won't overwrite
if already in sync.

## Process
1. Read the file at $ARGUMENTS
2. Search Notion for an existing page with the same title
3. If found: compare content, update only changed sections
4. If not found: create new page in the Engineering/Specs database
5. Return the Notion URL

Always ask before creating or updating anything.
Enter fullscreen mode Exit fullscreen mode

Usage:

> /push-to-notion docs/auth-refactor-spec.md
Enter fullscreen mode Exit fullscreen mode

Workflow 3 — Pull Feedback Back

After teammates have commented in Notion:

> "Fetch the auth refactor spec from Notion, show me all comments, and apply any approved changes to docs/auth-refactor-spec.md"
Enter fullscreen mode Exit fullscreen mode

Claude reads the page, extracts comments, applies changes to your local file. Your local file stays as the source of truth; Notion is the collaboration layer.

Workflow 4 — Daily Standup Prep 

> "Search Notion for all tasks assigned to me that are In Progress or Blocked. Also find any meeting notes from yesterday. Summarize what I worked on and what's blocking me."
Enter fullscreen mode Exit fullscreen mode

30-second standup prep from your terminal.

Workflow 5 — Create Meeting Notes

During or after a meeting, dictate or type bullet points, then:

> "Create a meeting note in Notion for today's architecture review. Attendees: Alice, Bob, Carlos. Here are my notes: [paste bullets]. Format it properly with Decisions and Action Items sections."
Enter fullscreen mode Exit fullscreen mode

Claude creates a properly formatted page in your Meetings database.

Workflow 6 — Query Your Database 

> "Show me all PRDs with status Draft that haven't been updated in the last two weeks"
> "List all open action items from meetings where I'm the owner"
> "Find every ADR we've made about database architecture"
Enter fullscreen mode Exit fullscreen mode

Natural language queries over your Notion databases — no Notion formula syntax required.

Workflow 7 — Generate Docs from Code

You just finished building a feature:

> "Read the code in src/auth/ and generate a technical runbook for this authentication system. Create it as a new page in the Engineering/Runbooks section of Notion."
Enter fullscreen mode Exit fullscreen mode

Claude reads your code, writes structured documentation, pushes it to the right place in Notion.

Part 6: Notion vs Obsidian — Honest Comparison

Since many people use both, here's the direct comparison:

Obsidian + Claude Code Notion + Claude Code
Setup time 30 seconds (just cd vault && claude) 15–20 minutes (MCP + OAuth)
Works offline Yes — plain files No — requires API
Team collaboration Needs Obsidian Sync or git Native — built in
Claude access method Direct file read/write MCP tools (structured)
Token efficiency High (plain text) High (Notion converts to Markdown)
Database queries No (just files) Yes — powerful
Comments/review No Yes
Mobile Via Obsidian app Via Notion app
Best for Personal knowledge, developers Teams, mixed technical/non-technical

Rule of thumb: solo developer or researcher → Obsidian. Team workflows or non-technical collaborators → Notion.

Part 7: Troubleshooting

OAuth flow doesn't start

# Force re-authentication
claude mcp remove notion
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude  # authenticate fresh
Enter fullscreen mode Exit fullscreen mode

"Page not found" errors
Notion MCP can only access pages explicitly shared with the integration. If you used Method B (manual), go to the Notion page → Share → Invite your integration.

With Method A (official plugin), OAuth grants access to your entire workspace automatically.

MCP server not showing in tool list

claude mcp list     # verify it's registered
claude doctor       # check for environment issues
Enter fullscreen mode Exit fullscreen mode

Headless / CI environments
OAuth requires a browser interaction — it won't work in fully automated pipelines. For CI, use the open-source server with a bearer token instead:

export NOTION_API_KEY=secret_xxxxx
claude mcp add --transport stdio notion-local \
  -- npx -y @notionhq/notion-mcp-server
Enter fullscreen mode Exit fullscreen mode

Note: the open-source server is no longer actively maintained by Notion. Use for automation only, not as your primary connection.

Part 8: Common Mistakes

Not telling Claude your workspace structure.
Claude searches by keyword. If your database is called "Q1 2026 Initiatives" but you ask for "current projects", it might not find it. Put your key database names in CLAUDE.md.

Giving Claude too broad access.
Start with one database. Add more as you verify behavior. Claude acts with your full permissions — broad access means broad possible impact.

Using it as a search engine only.
The real value is the loop: pull context → code → push back. If you're only doing read operations, you're using 20% of the capability.

Forgetting to share pages (Method B).
With manual setup, Claude can only see pages shared with your integration. New pages need to be shared individually unless you grant workspace-wide access during setup.

Quick Start Summary 

# 1. Install Claude Code
brew install --cask claude-code
claude auth login

# 2. Add Notion plugin (installs MCP + Skills + commands)
claude plugin add makenotion/claude-code-notion-plugin

# 3. Start a session and authenticate
claude
> /mcp   # complete OAuth in browser

# 4. Verify
> "List a random page from my Notion workspace"

# 5. Add workspace context to CLAUDE.md
> /init
# Edit CLAUDE.md to describe your Notion structure

# 6. First real workflow
> "Find my current sprint tasks and summarize what's in progress"
Enter fullscreen mode Exit fullscreen mode

Total setup time: under 20 minutes.

The Core Difference from Obsidian

With Obsidian, Claude Code is in your vault — it reads and writes files directly.

With Notion, Claude Code talks to your workspace — through structured MCP tools that Notion designed specifically for AI agents.

Both work. The Notion approach adds a connection layer but gains real-time sync, team collaboration, and database queries that file-based systems can't match.

If your work involves other people — specs that need review, meeting notes shared with a team, tasks tracked in a shared database — the Notion setup is worth the extra 15 minutes.

Based on official Notion MCP documentation (developers.notion.com), github.com/makenotion/claude-code-notion-plugin, shinzo.ai, hannahstulberg.substack.com, and code.claude.com/docs/en/mcp. April 2026.

Top comments (0)