Notion MCP Server: Setup Guide, Use Cases & Limitations

What Is Notion MCP Server?

Notion MCP Server exposes Notion’s API to Claude, enabling read and write operations on pages, databases, and blocks directly from an MCP-compatible client. It is maintained by Notion’s own engineering team (makenotion) on GitHub.

Quick Facts

What You Can Do With It

• Page creation: Instruct Claude to create new Notion pages with structured content inside any workspace your integration can access.
• Database queries: Query Notion databases by filter, sort, or property to retrieve rows as structured data.
• Content editing: Read and update existing page blocks, allowing Claude to append notes, rewrite sections, or restructure content.
• Knowledge base management: Traverse and modify nested page hierarchies to maintain documentation or team wikis programmatically.

How to Set It Up

Prerequisites: You need a Notion integration token. Create one at https://www.notion.so/my-integrations, set the required capabilities (read/write content, read databases), and share the relevant pages or databases with the integration.

Claude Desktop — add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_API_TOKEN": "your_notion_integration_token_here"
      }
    }
  }
}
**Claude Code** — run the following command to register the server:

```bash
claude mcp add notion -e NOTION_API_TOKEN=your_notion_integration_token_here -- npx -y @notionhq/notion-mcp-server

Replace your_notion_integration_token_here with the token from your Notion integration settings. After adding, restart the client so the server is detected.

Works Best With

Both Claude Code and Claude Desktop are explicitly supported. Claude Code suits scripted or terminal-driven workflows — querying databases, bulk-updating pages, or automating documentation tasks. Claude Desktop is better suited to interactive, conversational use like drafting and editing pages in the flow of a conversation.

Known Limitations

• Explicit page sharing required: The integration token only grants access to pages and databases that have been explicitly shared with the integration inside Notion. Workspace-wide access is not automatic, even with an admin token.
• Notion API rate limits apply: Notion enforces a rate limit of three requests per second per integration. High-volume operations (bulk page creation, large database queries) may trigger 429 errors.
• Block-level constraints: Some Notion block types (synced blocks, certain embed types) have limited or no write support through the API. Operations on these may silently fail or return errors.
• No binary file uploads: Attaching files or images to pages via the API is not supported in the standard integration scope; only text-based content operations are reliable.
• Token security: The integration token is passed as an environment variable. Avoid committing config files containing live tokens to version control.

Community Resources

• GitHub Issues: https://github.com/makenotion/notion-mcp-server/issues — the primary place to report bugs or check known issues
• Notion Developers Slack: Notion maintains an official developer community at https://developers.notion.com/ with a linked Slack workspace for API and integration questions
• Reddit: Discussions around Notion automation and MCP integrations surface in r/Notion and r/ClaudeAI