What happens when your Notion workspace stops being a passive filing cabinet and becomes an active collaborator that Claude can read from, write to, and manage in real time? That is the promise of the Claude MCP Notion architecture. The Model Context Protocol (MCP) is an open standard that lets AI assistants like Claude connect directly to external tools and databases. Instead of copying and pasting data between windows, Claude can perform actions inside your Notion workspace as if it were a human user clicking through the interface. This guide walks you through the exact setup, from generating your Notion integration token to resolving the most frustrating authentication errors, so you can build a genuinely useful AI powered database in under an hour.

What You’ll Build and the Architecture Behind It

The core concept is straightforward. MCP acts as a bridge between Claude and Notion. You run a small server on your machine (or use Notion’s hosted version) that exposes a set of tools. Claude discovers these tools and can call them to read a database, create a page, or update a property. The server handles authentication and translates Claude’s requests into Notion API calls. The result is a seamless loop: you ask Claude a question, it fetches the relevant data from your Notion pages, processes it, and optionally writes the result back.

There are two deployment options for the MCP server. The hosted Notion MCP (official, actively maintained) uses OAuth authentication and requires a user to log in via a browser. It is the recommended path for most developers because it requires no self hosting and is kept up to date. The alternative is the self hosted open source server from the makenotion/notion-mcp-server GitHub repository, which uses a bearer token (the ntn_ secret). That package is no longer actively maintained, but it can be useful for headless or fully automated workflows where a human cannot complete the OAuth flow every time. For this tutorial we will focus on the hosted version, as it is the most reliable and future proof choice.

Real world use cases go far beyond simple note retrieval. You can ask Claude to “Show me all open tickets in the Bug Tracker database” and get a formatted summary. You can instruct it to “Create a new page in the Content Calendar with today’s date and a status of Draft” and it will happen instantly. Some developers use this setup for context aware decision support: Claude checks their Core Identity database, current project load, and past decisions before recommending whether to take on a new consulting gig. Others build automated task management systems where Claude triages incoming requests and updates Notion without any copy pasting.

Prerequisites: Tools and Accounts

Claude MCP Notion prerequisites are minimal. You need three things installed and one account ready.

  • Node.js version 18 or later. The MCP server runs via npx, which ships with Node. Verify your installation by opening a terminal and typing node --version. If you see a version number starting with 18, 20, or 22, you are set. If not, download the latest LTS from the official Node.js website.
  • Claude Desktop or Claude Code. The free Claude Desktop app works perfectly for this. Install it from the Anthropic website and log in with your account. Claude Code (the terminal based agent) also supports MCP but the setup steps differ slightly. This guide assumes Claude Desktop.
  • A Notion workspace with at least one page or database you want to connect. Both free and paid plans work. You do not need a Notion AI subscription; the MCP integration is separate and independent.
  • Basic familiarity with editing JSON configuration files and running terminal commands. You will edit one file and run one npx command. If you have ever modified a .env file or a JSON config, you are more than qualified.

Creating Your Notion Integration and Obtaining the Token

Notion integration token MCP generation is the first active step. It is quick but requires careful attention to permissions.

  1. Open your browser and navigate to notion.so/my-integrations. You may need to log in if you are not already authenticated.
  2. Click the blue New Integration button. Give it a descriptive name such as “Claude MCP”. Under “Associated workspace”, select the workspace you want to connect. Under “Capabilities”, enable Read content and Update content. These two scopes allow Claude to both retrieve and modify data. You may also check “Insert content” and “Create content” if you plan to let Claude create new pages. For most developer workflows, read and update are sufficient.
  3. After clicking Submit, a secret token appears. It starts with ntn_ followed by a long string. Copy this token immediately and store it in a secure place such as a password manager or an encrypted file. You cannot see it again after you leave the page. Treat this token like a password; anyone with it can access the pages you authorize.
  4. Now you must give the integration permission to see specific pages. This is the step that trips up many people. Inside Notion, open the page or database you want Claude to access. Click the three dots in the top right corner, scroll down to Connections, and click “Add connection”. Find your newly created integration (e.g., “Claude MCP”) and select it. The page now shows that the integration can read and update its content. Repeat this for every page or database you want Claude to work with. Start small; you can always add more later.

Why is this manual permission step necessary? Notion enforces a security model where even internal integrations must be explicitly invited to each page. This prevents an integration from silently reading your entire workspace. It is a best practice that keeps your data safe, but it also means you must remember to grant access or Claude will return a 404 “page not found” error.

Configuring the MCP Server in Claude Desktop

Now we wire everything together using a JSON configuration file. This is where the Claude Desktop MCP server config lives.

  1. Locate the Claude Desktop configuration directory. On macOS it is ~/Library/Application Support/Claude/. On Windows it is %APPDATA%\Claude\. Inside that folder you will find a file named claude_desktop_config.json. If it does not exist, create it.
  2. Open the file in a text editor. The JSON should contain a top level mcpServers object. Add the following entry. Replace ntn_your_token_here with the secret token you copied earlier. 
    {
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_your_token_here\", \"Notion-Version\": \"2022-06-28\"}"
      }
    }
  }
}
    Pay close attention to the quoting. The env value must be a properly escaped JSON string. Notice the double backslashes before the inner quotes. If your editor does not handle this correctly, you can use single quotes in some shells, but for JSON you must escape each inner double quote with a backslash. A common pitfall is missing the backslashes, which causes the MCP server to receive a malformed header string and respond with 401 errors.
  3. Save the file. If Claude Desktop is already running, you must restart it completely (quit and reopen) so it reads the new configuration. On the first launch after configuring, Claude will attempt to start the Notion MCP server. You should see no obvious error messages. If you do see an error, double check the JSON syntax with an online validator and ensure your token is correct.

That is the entire configuration. The npx -y @notionhq/notion-mcp-server command downloads and runs the official Notion MCP server package on demand. The OPENAPI_MCP_HEADERS environment variable contains the authentication header that the server will pass to every Notion API request.

Testing the Connection and Basic Operations

With the configuration saved and Claude restarted, you can now run your first Claude Notion MCP test commands.

Start with a simple read query to verify the connection:

“Show me the contents of my Tasks database.”

If you have a database named “Tasks” and you have given the integration access to that page, Claude should respond with a list of entries, their titles, and any other properties it can see. If you get a response like “I cannot find a database with that name”, check that the name is exact and that the integration is connected to that page.

Once read works, test creating a new page:

“Create a page in my Dev Toolkit database with a title ‘Fix login bug’ and a status of ‘Backlog’.”

Claude will call the MCP server’s create tool. If successful, it will confirm the new page ID and title. Open Notion to see the page appear.

Next, update an existing page:

“Update the status of the page titled ‘Fix login bug’ to ‘In Progress’.”

Claude will locate the page by title (be careful with exact matching) and call the update tool to change the Status property. This works for any property you have defined in your database, including select, multi select, date, people, and URL fields.

For a more advanced test, ask Claude to perform a filtered query:

“Show me all tasks in the Bug Tracker that have a priority of High and are not yet completed.”

Claude will translate this into a database query with filters. If your schema matches, you will get a concise list. If not, Claude will explain that it cannot find the specified properties, which helps you refine your database design.

Avoiding Common Pitfalls with Authentication and Terminal Commands

Notion MCP authentication errors are the most common source of frustration during setup. Here are the issues you are likely to encounter and how to fix them.

1. Invalid grant errors. If you see “invalid_grant” when using the hosted OAuth version, it usually means the authorization code has expired or the state parameter did not match. The fix is to disconnect the integration in Claude’s MCP settings and reconnect from scratch. On the self hosted version, an “invalid_grant” on token refresh means the secret token itself is invalid or has been revoked. Go back to your Notion integrations page, confirm the token is still active, and copy it again if needed.

2. Server reconnection failures after OAuth. This is a known bug (see GitHub issue #167). After the OAuth flow completes successfully, the MCP client fails to persist the tokens, causing a “Loading tools… fetch failed” loop. The workaround is to disconnect the integration in Claude’s MCP settings panel, then add it again. This forces a fresh OAuth handshake and usually resolves the issue. If it persists, try clearing the MCP server cache by deleting the ~/.claude/mcp-servers directory (if it exists) and restarting Claude.

3. Improper quoting of the OPENAPI_MCP_HEADERS environment variable. In the self hosted configuration, if you use a shell script to pass the token, be extremely careful with quoting. JSON inside environment variables needs double escaping. The example config above is tested and works on both macOS and Linux. On Windows, you may need to use escaped quotes differently. A safer alternative is to set the environment variable in a separate .env file if your system supports it, but the claude_desktop_config.json approach is the official recommendation.

4. Integration not given page access. This is the single most overlooked mistake. You can have a perfect token and config, but if the integration is not explicitly added to a page’s Connections list, every MCP call to that page will return a 404 or “page not found” error. Always verify by opening the page in Notion, clicking the three dots, and checking that your integration name appears under Connections.

5. Rate limiting. Notion’s API has a rate limit of roughly 3 requests per second (around 180 per minute). If you build a script that makes many rapid calls, you will hit this limit and get a 429 response. The MCP server does not handle retries automatically. Plan your queries to stay under the limit, or use a batch strategy that spaces requests out. For most development workflows this is not an issue.

Going Further: Best Practices and Advanced Workflows

Once the basic connection is reliable, you want to follow Claude MCP Notion best practices to avoid data loss and maintain context.

Document your MCP setup in a CLAUDE.md file. If you use Claude Code, create a CLAUDE.md file in your project root that lists the Notion databases Claude can access, the schema of each, and any special instructions. This file is automatically loaded into Claude’s context every session, so it remembers the structure without you repeating it. You can ask Claude to “Add documentation about our Notion sync setup to my CLAUDE.md file” and it will do the work.

Use a stable Notion architecture. A flat list of pages works for testing, but for production you want a hub and spoke design. Consider a PARA style home page with links to dedicated databases for Projects, Areas, Resources, and Archives. This prevents Claude from reading an entire workspace when you only need a specific project. It also keeps context window usage efficient.

Lock down the integration token to minimum scopes. Start with read only. Add update and create only when a specific workflow requires it. Never use an integration token that has “delete” capabilities unless you absolutely need it. The hosted OAuth version already enforces scopes, but the self hosted server’s bearer token grants full access to any page the integration is connected to, so be careful.

Consider the self hosted server for headless automation. If you need Claude to run automated tasks without a human present (e.g., a nightly script that syncs issues), the self hosted open source server with a bearer token is your only option. But note that Notion has soft deprecated that package. It still works as of 2026, but new features and bug fixes are unlikely. For interactive use, the hosted OAuth version is superior.

Test push and pull cycles with small edits first. Always do a “compare before sync” step: ask Claude to show you what it is about to change, then confirm. Blind overwrites can delete data if two collaborators edited the same page. Claude cannot resolve merge conflicts; you must do that manually.

Frequently Asked Questions

Q: Do I need a Notion AI subscription to use MCP?
A: No. The MCP integration is independent of Notion AI. You use Claude’s AI capabilities, and the MCP server talks directly to the Notion API. Free and paid Notion plans both work equally well. The only requirement is that your workspace has API access, which all plans include.

Q: Why do I keep getting “Authentication successful, but server reconnection failed”?
A: This is a known issue with some MCP clients, particularly when using the hosted OAuth version. The fix is to disconnect the integration in your tool’s MCP settings and reconnect. If that does not work, clear the local MCP cache by removing the ~/.claude/mcp-servers folder and restarting the application. The problem often occurs because the OAuth token is not properly persisted by the client.

Q: Can I use this setup with tools other than Claude, like Cursor or VS Code?
A: Yes. Many code editors and AI tools now support the MCP standard. You can add the same Notion MCP server configuration to Cursor’s MCP settings or any other MCP compliant client. The authentication flow and JSON configuration are identical. The official Notion documentation at developers.notion.com provides instructions for popular tools.

Next Steps

You now have a fully functional Claude MCP Notion pipeline. The immediate next step is to ask Claude to create a few databases that mirror your own workflows: a project tracker, a content calendar, or a bug backlog. Experiment with asking it to run weekly reviews that summarize progress and flag overdue tasks. As you get comfortable, explore the broader MCP ecosystem: you can connect Claude to GitHub, Google Sheets, or PostgreSQL using similar configuration patterns. For an alternative approach to connecting Claude to a spreadsheet tool, see our guide on how to connect Claude to Google Sheets.

The most important takeaway is that MCP transforms Notion from a passive repository into an active, AI driven layer in your workflow. Your second brain no longer just stores information; it understands you and acts on your behalf.

Cover photo by Aron Visuals on Unsplash.