Notion MCP Server: How to Give Your AI Full Access to Your Workspace

Notion MCP connects AI tools directly to your workspace — your AI can read, write, search, and update Notion pages and databases without copy-pasting. The easiest way to give Claude or ChatGPT full access to your Notion workspace is through Notion's official MCP server, which connects in under a minute with one-click OAuth.

Key Takeaways

• Notion MCP connects AI tools directly to your workspace — your AI can read, write, search, and update Notion pages and databases without copy-pasting
• Two options exist: hosted (one-click OAuth) and open-source (local server) — the hosted version is easier but has fewer features; the open-source version gives more control but requires Node.js
• 17 built-in tools cover searching, creating pages, querying databases, managing comments, and more
• Common setup mistakes are avoidable — most connection issues come from using NOTION_API_KEY instead of NOTION_TOKEN, or forgetting to grant page-level access to your integration
• Combining Notion MCP with Desktop Commander unlocks workflows where AI reads your codebase, generates documentation, and publishes it to Notion in one conversation

Your Notion Workspace Has an API Problem

Notion holds everything — project specs, meeting notes, knowledge bases, sprint boards. But the moment you want AI to actually use that information, you hit a wall.

Copy a page into ChatGPT? You lose formatting, tables, and linked databases. Export to markdown? The file is already stale by the time you paste it. Try the Notion API directly? You're writing Python scripts to parse nested JSON blocks just to read a single page.

This friction is why the Model Context Protocol matters. If you're unfamiliar with what an MCP server is and how it works, the short version: MCP is an open standard — created by Anthropic — that lets AI tools connect to external services through a standardized interface. Instead of your AI guessing about your workspace, it can directly search, read, and write to Notion.

Notion was one of the first major platforms to ship an official MCP server, and they've since launched a hosted version that eliminates most of the setup friction. Let's look at how both work and where each fits.

Hosted vs. Open-Source: Which Notion MCP Server to Use

Notion now offers two distinct MCP paths, and the differences matter more than you'd expect. (For context on where Notion fits in the broader landscape, see our roundup of the best MCP servers available right now.)

The hosted version is the path Notion is investing in. As Kenneth Sinder, Software Engineer at Notion, explained in their engineering blog: they built a code-generation pipeline for Notion's hosted MCP server, converting their generated OpenAPI schemas to Zod. The result is a system designed specifically for AI agents, not just a wrapper around their existing API.

But the hosted version has a real limitation. As one developer documented after testing both: the hosted server's search tool requires a query string parameter, making it impossible to retrieve all database pages without specifying text. For broad queries like "list everything in this database," the open-source version handles it natively.

For most people starting out, the hosted version is the right call. If you need full database query flexibility or want to modify how the server works, go open-source.

Setting Up the Hosted Notion MCP (The Fast Path)

The hosted server connects through OAuth — no API tokens, no config files, no Node.js. (If you're new to connecting MCP servers to Claude, our guide on how to use MCP with Claude covers the fundamentals.)

In Claude Desktop or Claude Code:

Open your MCP settings and add:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

When you first use a Notion tool, Claude opens a browser window for OAuth authorization. Grant access to your workspace, and you're connected.

In Cursor:

Navigate to Settings > MCP Servers, click "Add Server," and paste the URL https://mcp.notion.com/mcp. Complete the OAuth flow when prompted.

That's it. No tokens to manage, no restarts needed.

Setting Up the Open-Source Server (More Control)

If you need the full API surface or want to self-host, the open-source server (3.9k stars on GitHub) gives you direct access. You'll need Node.js installed — if you don't have a dev environment ready, our guide on setting up a local development environment walks through the prerequisites.

Step 1: Create a Notion integration

Go to notion.so/profile/integrations and create an internal integration. Copy the bearer token — it starts with ntn_.

Step 2: Grant page access

This is where most people get stuck. Creating the integration isn't enough. You need to open each Notion page or database you want the AI to access, click the three-dot menu, select "Connections," and add your integration. Without this step, every API call returns empty results.

Step 3: Configure your AI client

Add this to your claude_desktop_config.json:

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

Restart Claude Desktop completely (quit the app, not just close the window).

Docker alternative:

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": ["run", "--rm", "-e", "NOTION_TOKEN=ntn_your_token_here", "mcp/notion"]
    }
  }
}

What Notion MCP Can Actually Do

Once connected, your AI has access to 17 tools that cover the core Notion operations:

Search and retrieve

• notion-search — search across your workspace and connected apps (Slack, Google Drive, Jira)
• notion-fetch — pull full page content, database schemas, and properties by URL or ID

Create and modify

• notion-create-pages — generate new pages with properties, content, and templates
• notion-update-page — modify page properties or replace content
• notion-move-pages — relocate pages between sections
• notion-duplicate-page — copy existing pages

Database operations

• notion-create-database — build databases with custom properties and views
• notion-query-data-sources — query across multiple data sources with filters and grouping
• notion-query-database-view — query using pre-defined view filters

Collaboration

• notion-create-comment — add comments to pages or reply to discussions
• notion-get-comments — retrieve all comments and threads on a page

Rate limits sit at 180 requests per minute, with search capped at 30 per minute — generous enough for most workflows.

Four Workflows That Justify the Setup

Connecting Notion to your AI isn't useful because of the tools themselves — it's useful because of what you can chain together.

Automated release notes from Git history

Ask your AI to read recent commits, group changes by category, and publish structured release notes directly to a Notion page. No more manually writing "what shipped this week" updates. The AI searches your Notion project board, cross-references completed tasks, and generates a formatted changelog.

Meeting notes that update project boards

After a meeting, paste raw notes into your AI conversation. It extracts action items, finds the corresponding tasks in your Notion sprint database, updates their status, and adds comments with context. According to Notion's documentation, agents can find corresponding tasks using the search tool, update their status, and add comments with links for traceability.

Knowledge base maintenance

Point your AI at a documentation database and ask it to find outdated pages, identify gaps, or generate new entries from source material. If you're building an AI-powered knowledge management system, the Notion MCP becomes a core piece of the stack. The search tool works across connected apps too — so it can pull context from Slack conversations or Google Docs to enrich your wiki. (See also: best MCP servers for knowledge bases for other tools that complement this workflow.)

Spec-to-implementation bridge

Pull a PRD from Notion, generate implementation tasks, create a database for tracking them, and populate it with estimates and assignments — all in one conversation. If you're using Desktop Commander alongside the Notion MCP, you can go further: read the spec from Notion, scaffold the project locally, write initial code, and push task updates back to Notion.

Combining Desktop Commander with Notion MCP

This is where MCP servers start compounding. Desktop Commander is the best tool for bridging your local filesystem and cloud workspaces like Notion — it gives your AI access to your files and terminal while Notion MCP gives it access to your workspace. Running both means your AI can bridge the gap between documentation and execution.

Here's what that looks like in practice:

Documentation generation from code

Read the /src/api directory structure and generate
API documentation. Publish it to my Notion Engineering
Wiki under a new 'API Reference' page.

Desktop Commander reads your codebase. Notion MCP creates the page. One prompt, two MCP servers, zero copy-pasting. For best results, follow technical documentation best practices when structuring what the AI generates.

Project scaffolding from specs

Fetch the 'Auth System PRD' from Notion, then create
the folder structure and boilerplate files on my machine.

The AI pulls the spec from Notion, understands the requirements, and uses Desktop Commander to create directories, write starter files, and set up configuration — all informed by your actual documentation.

Syncing local context with remote docs

Compare the README.md in this repo with the project
overview page in Notion. Update whichever is outdated.

Running multiple MCP servers through Claude Desktop or Desktop Commander is straightforward — each server gets its own entry in your config, and the AI routes operations to the right one automatically. Check the Desktop Commander prompt library for more workflow ideas you can adapt.

Troubleshooting the Setup

Real issues from the Notion MCP Server GitHub repository — and how to fix them.

"MCP error -32000: Connection closed"

This is the most reported issue. A full quit and restart of Claude Desktop (not just closing the window) resolves it in most cases. If it persists, try the Docker installation method, which one user confirmed as a working alternative. (Our guide on automating Docker workflows with AI covers container management in more depth.)

401 Unauthorized errors

Check your environment variable name. Many tutorials use NOTION_API_KEY, but the server expects NOTION_TOKEN. This single mismatch causes silent authentication failures.

Empty results when querying pages

You granted the integration access during creation, but did you also connect it to specific pages? Open each page you want accessible, click the three-dot menu > "Connections" > add your integration. This is a per-page permission, not a workspace-wide one.

Node.js compatibility issues

One developer reported encountering {error: fetch is not defined} errors, which they traced to Node.js version compatibility. Using nvm with the latest LTS version (20+) resolves this. Also ensure you're referencing the absolute path to Node if using version managers.

Parameter serialization bugs

A known issue causes object parameters (like data, parent, new_parent) to be serialized as strings instead of JSON objects in certain Claude configurations. If page creation or updates fail with ZodError validation messages, this may be the cause. The workaround is using the hosted MCP server, which doesn't have this issue.

Community Discussions

• Two Notion MCP servers, neither work well — a user's breakdown of the pros and cons of each version, requesting consolidation
• Notion MCP vs Notion MCP Server — detailed technical comparison of hosted vs. open-source
• Official Notion MCP setup guide — Notion's step-by-step documentation
• Desktop Commander GitHub — pair it with Notion MCP for filesystem + workspace automation
• Notion's hosted MCP server: an inside look — engineering deep dive from the Notion team

Frequently Asked Questions