Notion Integration MCP Server

Overview

The Notion Integration MCP serves as a bridge between large language models and Notion workspaces, enabling AI assistants to interact with your Notion content. This integration supports a wide range of operations including reading and writing pages, querying databases, managing blocks, and handling comments.

Prerequisites

Before setting up the Notion Integration MCP, you'll need:

1. A Notion account with access to the workspace you want to integrate
2. Permission to create integrations in your Notion workspace

Installation

To install and configure the Notion Integration MCP, follow these steps:

Step 1: Create a Notion Integration

1. Visit the Notion Integrations page
2. Click "New Integration"
3. Name your integration (e.g., "Claude Assistant")
4. Select the appropriate capabilities:
   • "Read content" (required)
   • "Update content" (if you want to allow writing)
   • "Insert content" (if you want to allow creating new content)
5. Complete the integration creation process

Step 2: Get Your Integration Token

After creating the integration, you'll be provided with an "Internal Integration Token." This is your NOTION_API_TOKEN that will be used to authenticate the MCP.

Step 3: Add the Integration to Your Workspace

For each page or database you want the AI to access:

1. Open the page/database in Notion
2. Click the "•••" menu in the top right corner
3. Select "Connections"
4. Find and select your newly created integration
5. Click "Confirm" to grant access

Step 4: Configure Your AI Client

Add the following configuration to your AI client's configuration file (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token-here"
      }
    }
  }
}

Advanced Configuration

Enabling Markdown Conversion

To reduce token consumption when viewing content, you can enable the experimental Markdown conversion feature:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token-here",
        "NOTION_MARKDOWN_CONVERSION": "true"
      }
    }
  }
}

With this feature enabled, you can control the format on a per-request basis:

• Use "format": "markdown" for better readability when only viewing content
• Use "format": "json" when you need to modify the returned content

Limiting Available Tools

If you want to restrict the MCP to only use certain tools (for example, to create a read-only integration), you can specify the enabled tools using the --enabledTools argument:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y", 
        "@suekou/mcp-notion-server", 
        "--enabledTools=notion_retrieve_block,notion_retrieve_block_children,notion_retrieve_page,notion_query_database,notion_retrieve_database,notion_search"
      ],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token-here"
      }
    }
  }
}

Troubleshooting

If you encounter issues with the Notion Integration MCP:

1. Permission Errors: Ensure your integration has the necessary permissions and is invited to all relevant pages/databases.

2. Authentication Errors: Verify your NOTION_API_TOKEN is correct and properly configured in your client settings.

3. Content Not Appearing: Check that the integration has been explicitly added to each page or database you want to access.

4. Editing Issues with Markdown Conversion: When using Markdown conversion, switch to JSON format ("format": "json") when you need to edit content to preserve the original structure.