What You’ll Build & Prerequisites

By the end of this guide, you’ll have a working Claude Notion MCP integration that lets you read, create, and update Notion databases directly from Claude. No more copy-pasting tasks or manually updating project boards. You’ll type natural language commands like “Add a new blog post idea to my Content Calendar” — and it just works.

MCP (Model Context Protocol) is Anthropic’s open standard for connecting AI models to external tools. Think of it as a universal plugin system: instead of building brittle API wrappers, you install a lightweight server that handles authentication, error handling, and data formatting. The result is a clean, two-way bridge between Claude and your Notion workspace.

Prerequisites:

  • Claude Pro account — needed for Claude Desktop or API access.
  • Notion account (any plan works) with admin access to create integrations.
  • Node.js v18+ installed on your machine. (Download Node.js)
  • Basic terminal familiarity — you’ll run 4–5 commands total.
  • A text editor to edit a small JSON config file.

If you’ve never touched the command line before, don’t sweat it. I’ll explain every command, and the payoff — a personal AI assistant wired into your actual data — is worth the few minutes of setup.

Step 1: Create a Notion Integration and Obtain an API Token

Target Keyword: Notion API token MCP

The first concrete step is getting a Notion API token that will authenticate your MCP server. Notion uses a simple secret-token model — no OAuth dance for internal integrations.

1. Open the Notion Developers portal and click New Integration.
2. Name it something descriptive like “Claude MCP Assistant” and select the workspace you want to use.
3. Click Submit — you’ll instantly see an Internal Integration Secret. Copy this token and store it securely. You’ll use it in Step 3.

4. Go to any Notion database you want Claude to access (e.g., a “Tasks” or “Content Calendar” database). Click the three dots in the top-right corner, select Connections, click Add connection, and choose your newly created integration. You must do this for every database — Notion doesn’t grant workspace-wide API access by default.

5. Quick sanity check: run this command in your terminal (replace YOUR_TOKEN_HERE with the actual token):

curl -X POST 'https://api.notion.com/v1/databases' \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE' \
  -H 'Notion-Version: 2022-06-28'

If you get a {"object":"list","results":[]} response, the token works. A 401 means your token is invalid or the integration hasn’t been shared with any databases.

⚠️ Security note: Treat this token like a password. Never commit it to version control. Use environment variables or a secrets manager in production.

Step 2: Install the MCP Server for Notion

Target Keyword: install MCP server Notion

Now we install the official MCP server package that translates Claude’s requests into Notion API calls. It’s an npm package published by Anthropic.

Open your terminal and run:

npm install -g @anthropic/mcp-server-notion

This installs the server globally (-g flag) so you can run it from any directory. Alternatively, if you prefer a project-local install (cleaner for version control):

mkdir claude-notion-mcp && cd claude-notion-mcp
npm init -y
npm install @anthropic/mcp-server-notion

Verify the installation with:

mcp-server-notion --help

You should see a list of available commands and options. If the command isn’t found, you may need to add npm global bin to your PATH, or use npx instead (e.g., npx @anthropic/mcp-server-notion --help).

What this server does under the hood: It listens on a local port and implements the MCP protocol — JSON-RPC messages with specific methods like tools/list, tools/call, and resources/read. When Claude asks to “get tasks,” the server fetches them from Notion, formats them, and sends them back. You don’t need to worry about the nuts and bolts, but understanding that it’s just a local HTTP server helps with debugging.

Step 3: Configure the MCP Server with Your Token

Target Keyword: MCP server configuration

Configuration is done through a JSON file that tells Claude how to launch the server and what environment variables to pass. This is where your Notion API token MCP goes.

Create a file called mcp.json in a location you’ll remember. I recommend ~/.claude/mcp.json for global use.

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-server-notion"
      ],
      "env": {
        "NOTION_API_TOKEN": "your_token_here"
      }
    }
  }
}

Replace your_token_here with the actual token from Step 1. Important: Do not include any extra spaces or trailing commas — that breaks JSON readability.

Optionally, you can specify a DEFAULT_DATABASE_ID environment variable to target a single database without needing to specify it in every query. Find the database ID from the URL of your Notion page (it’s the string after the workspace name and a slash, typically a 32-character hex).

Why separate config? This design keeps your token out of command history and makes it easy to switch between different profiles (e.g., work vs. personal) by using different config files.

Step 4: Connect the MCP Server to Claude

Target Keyword: Claude MCP configuration

Now we wire up Claude to use the server we just configured. The method depends on whether you’re using Claude Desktop (GUI) or Claude API (programmatic).

Claude Desktop (Recommended for Testing)

1. Open Claude Desktop and go to Settings → Developer → MCP Servers.
2. Click Add MCP Server and provide the full path to your mcp.json file (e.g., /Users/yourname/.claude/mcp.json).
3. Restart Claude Desktop completely. You should see a small plug icon in the input bar indicating connected tools.

Claude API (Programmatic Access)

If you’re building a custom app, set the mcp_config parameter in your API request to point to the same JSON file. Example using the Anthropic SDK (conceptual):

const response = await anthropic.messages.create({
  model: "claude-3-5-sonnet-20241022",
  max_tokens: 1024,
  mcp_config: { config_path: "/path/to/mcp.json" },
  messages: [{ role: "user", content: "List my tasks" }]
});

Command-Line Fallback

You can also start the server manually in a terminal:

mcp-server-notion

Then, in a separate terminal, run Claude with the --mcp flag (if using Claude CLI). This is useful for debugging — you’ll see live logs.

Opinion: Start with Claude Desktop. It gives you instant feedback and eliminates the friction of coding. Once you’re confident the integration works, migrate to API-based workflows.

Step 5: Test Your Integration with Real Queries

Target Keyword: test Claude Notion MCP

Time to see if wires actually connect. Open a chat with Claude and ask a read query:

"List all pages in my Notion database named Tasks"

If Claude responds with a list of your tasks (or notes that the database is empty), congratulations — your Claude Notion MCP integration is live.

Next, try a write query:

"Add a task to my Tasks database: Buy groceries, due tomorrow"

Claude should confirm the creation. Open Notion and check the database — the new page should appear with the title and property you specified.

Debugging tips if things go wrong:

  • Run the MCP server in debug mode: add --debug to the command or the args in your config. You’ll see raw JSON-RPC requests flowing.
  • Check that the Notion integration has been shared with the specific database you’re querying. This is the #1 cause of “permission denied” errors.
  • Ensure your token has both read and write capabilities (the default is both). If you created a read-only integration, re-create it.
✅ Real example: I used this setup to replace my morning standup ritual. Every day at 9 AM, a cron job triggers a Claude script that reads my Notion task board, summarizes what’s overdue, and posts the summary to Slack. Setup time: 20 minutes. Time saved per week: ~2 hours.

Common Pitfalls and Next Steps

Target Keyword: MCP integration troubleshooting

Even with a clean setup, a few things can trip you up. Here’s what I’ve seen most often:

  • Token not shared with database: You can have a perfect token and still get “not found” errors if the integration isn’t connected to the target database. Check Notion’s Connections menu on every database you want to query.
  • Config file formatting: Trailing commas, unmatched quotes, or using single quotes in JSON will break everything. Use a linter or validator.
  • Server not running before Claude Desktop: Claude Desktop starts the MCP server automatically based on your config. If it fails silently, check the Developer logs in Claude Desktop (Settings → Developer → Console).
  • Mismatched Notion API version: The MCP server uses 2022-06-28. If your database uses newer properties, some may not be recognized. Stick to simple properties (text, select, date) for initial testing.

Next Steps: Once you’re comfortable with single-database queries, level up:

Why this matters for founders: Most teams pay for five different tools that duplicate data entry. MCP lets you collapse that stack into a single interface — Claude, talking directly to your source of truth. It’s not just about saving time; it’s about data integrity. When Claude is the only place you update projects, and it writes directly to Notion, you eliminate manual sync errors. That’s a competitive edge.

Cover photo by Julien Tromeur on Pexels.