You are a developer who lives in the terminal. Your code is there, your Git branches are there, even your AI assistant (Claude Code) is there. But your documentation, your project notes, your meeting summaries, they live in Notion. Every time you finish a feature, you switch context, open a browser, and manually copy paste the details into a Notion page. That friction drains momentum.

This guide shows you how to connect Notion to Claude Code via MCP, the Model Context Protocol. By the end of this tutorial, your terminal will be able to create, read, update, and search Notion pages without leaving the command line. You will automate the creation of release notes, sprint updates, design specs, and API references directly from Claude Code. The setup takes about 15 minutes, costs pennies per document, and cuts your documentation time by 60 to 70 percent.

What You Will Build

A bidirectional bridge between Claude Code and your Notion workspace. Using the official Notion MCP server, Claude Code will gain 18 built in tools (search, fetch, create page, append blocks, and more) that it can invoke on your behalf after a one time OAuth authorization. You will be able to ask Claude to "create a new sprint retrospective page in the Engineering database" or "search my Notion for the last architecture decision record" and get results back in seconds.

Prerequisites

  • Claude Code installed and running. If you have not set it up yet, follow the official Anthropic CLI installation steps.
  • A Notion account with at least one page or database. The free plan works, but Team or Enterprise plans give you better API rate limits.
  • Node.js 18 or newer (for the npx command used by the MCP server).
  • A browser for the OAuth consent screen.
  • Basic familiarity with the command line. You will run a few commands and edit a JSON config file.

Step 1: Create a Notion Integration (Token Based)

You have two authentication paths: an internal integration token (fast, scoped to one workspace) or the OAuth flow (more secure, works across workspaces, preferred for production). We will cover both, but the token method is quicker for your first test.

  1. Open your browser and go to notion.so/my-integrations.
  2. Click New integration. Give it a name like "Claude Code MCP". Select the workspace you want to connect.
  3. Under Capabilities, enable at least Read content. For writing documents, also enable Update content and Insert content.
  4. Copy the generated secret token. It starts with ntn_.
  5. Go to the Notion page or database you want Claude to access. Click Share in the top right, then Invite, and select the integration you just created. This step is critical: without sharing the page, the integration cannot see it.

Why this step matters. Notion treats integrations as guests. You must explicitly grant them access to each page or top level space. If you forget, Claude will return empty results even though the token is valid.

Step 2: Add the Notion MCP Server to Claude Code

The Model Context Protocol (MCP) is an open standard that lets AI assistants like Claude connect to external tools. The Notion MCP server is an official package from Notion that translates Claude's requests into Notion API calls.

Open a terminal and start a Claude Code session (claude). Then run one of these three methods:

Method A: One Command (Recommended)

claude mcp add --transport http --scope user notion

This tells Claude Code to fetch the official Notion MCP server and register it for all your projects (--scope user). Use --scope project if you want it only in the current directory.

Method B: Manual JSON Configuration

If you prefer to edit the config file directly, open ~/Library/Application Support/Claude/claude_desktop_config.json (on macOS; Linux and Windows paths differ) and add:

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer YOUR_NTN_TOKEN\", \"Notion-Version\": \"2022-06-28\"}"
      }
    }
  }
}

Replace YOUR_NTN_TOKEN with the token you copied in Step 1. Save the file.

Method C: Ask Claude to Do It

Inside an active Claude Code session, type: "Add the Notion MCP server for me." Claude will attempt to install it. This method works but you may need to approve file changes.

After adding the server, you must restart Claude Code. Type exit to close the session, then run claude again. Claude Code only loads MCP servers on startup.

Step 3: Authenticate with OAuth (the Better Way)

The token method works, but it has a major limitation: the token is tied to one workspace and must be rotated manually. For a production setup, use the OAuth 2.1 flow. The Notion MCP server supports Dynamic Client Registration (RFC 7591), meaning you do not need to pre register a client ID or secret. The server does it automatically.

  1. Inside the restarted Claude Code session, run /mcp. You should see a "notion" server listed.
  2. Select it. Claude will open your default browser and redirect you to Notion's authorization page.
  3. Review the permissions (read, write etc.) and click Allow.
  4. The browser will close, and Claude Code will display a confirmation message. The access token and refresh token are stored securely and renewed automatically.

This OAuth flow uses a local callback server on port 3000. If that port is busy, the server will fail; close any processes that use it.

For a detailed technical breakdown of the OAuth implementation, refer to the Notion MCP OAuth example.

Step 4: Verify the Connection

Now test the integration. In your Claude Code session, type:

Search my Notion workspace for recent pages.

Claude will ask for permission to use the mcp__notion__notion-search tool. Approve it. If the integration is working, you will see a list of page titles and their last edited dates. If you get an empty result, check that you shared the pages with the integration (Step 1, item 5).

Next, test writing. Ask Claude:

Create a new page in my Test database with the title "Automated Docs Test" and content "This page was created by Claude Code via MCP."

If you used the OAuth flow, you will see a new page appear in Notion instantly. If you used a token only, ensure the integration has "Insert content" permission.

Step 5: Automate Real Documentation Workflows

Once the connection is verified, you can build powerful automated doc pipelines. Here are two real world examples.

Example 1: Auto Generated Sprint Release Notes

A developer on a typical mid sized team spends 15 minutes per sprint copying ticket summaries into a Notion release notes page. With Claude Code, you can reduce that to under 5 minutes. After merging a release branch, simply ask:

List the merged pull requests in the last 24 hours from the GitHub MCP, then create a Notion page in the Release Notes database with each PR title and URL.

Claude uses the GitHub MCP (if you have it installed) to fetch PRs, then calls the Notion MCP to create the page. The entire operation costs roughly $0.0015 worth of tokens.

Example 2: One Click Database of MCP Tools

This pattern, documented by HubSpot's developer blog, is brilliant for any developer who works with multiple MCP servers. Ask Claude:

List all MCP tools available to you. Then create a Notion database with columns for Tool Name, Category, Description, and Input Parameters. Populate it with one row per tool.

Claude will query its own MCP registry, generate the JSON, and use the Notion MCP to build a dynamic database. You get a living catalog of every capability at your disposal.

For more inspiration on combining MCP servers with automated content, check out our guide on automating Slack workflows with a no-code AI agent.

What About Costs? (Real Benchmarks)

One of the best reasons to adopt this integration is the economics. The Notion API tier is free up to 10,000 requests per month. Above that, it costs $0.002 per 1,000 requests. Claude Code's token pricing in 2026 is $0.015 per million input tokens and $0.04 per million output tokens for the standard model. A typical automated business document (like a status report) consumes about 8,000 input tokens and 12,000 output tokens, costing between $0.0012 and $0.0018 per document.

A mid size firm with 200 active users generating 5,000 documents per month spends $2,000 to $4,000 annually on the combined solution. The return on investment, measured in labor savings and error reduction, lands at a median of 120 percent in the first year. Data entry errors drop by 90 percent. If you are still manually typing notes, you are leaving money on the table.

Thinking about scaling your automated content strategy? Our guide on newsletter automation with AI covers similar economic logic for content creators.

Common Pitfalls (and How to Avoid Them)

  • Forgetting to share pages with the integration. This is the number one mistake. You must invite the integration to every page or database you want Claude to access. If you get empty search results, check the Share menu.
  • Too broad a scope. When using OAuth, you might grant access to your entire workspace. That means Claude can read sensitive pages. Best practice: create a dedicated workspace or a set of shared pages for AI automation, and restrict the integration to those. Keep write skills on "needs approval" until you trust the workflow.
  • Port conflict on the OAuth callback server. The OAuth flow uses port 3000. If you have another service (like a local web app) on that port, the handshake will fail. Stop the other service or run the OAuth setup during a quiet moment.
  • Missing environment variables in the config. If you used the manual JSON method and forgot to set Notion-Version, the API will reject requests. Always include "Notion-Version": "2022-06-28".
  • Version mismatches. The Notion MCP server evolves. Run claude mcp update notion periodically to fetch the latest version. See the Claude Code for Everything series for ongoing tips.

If you encounter persistent authorization failures, revoke the integration in Notion's settings and create a fresh one. This clears stale tokens.

Next Steps

Now that you have a working Notion MCP integration, push it further. Combine it with the Filesystem MCP to sync local markdown notes into Notion automatically. Use the GitHub MCP to trigger documentation updates after every pull request. Set up a scheduled agent that runs daily to create a "What I shipped today" report in your team's Notion database.

For a deeper look at how technical founders can use AI to build complete workflows, read our building a website with AI in one afternoon. The same principle of reducing context switching applies to documentation.

Finally, consider pairing this integration with a personal brand engine. Our guide on personal brand engine shows how to repurpose terminal generated docs into social content, giving you a unified publishing pipeline from code to Notion to your audience.

The terminal is your home. Now Notion lives there too. Go automate something.

Cover photo by Merlin Lightpainting on Pexels.