Notion MCP

Notion

Notion's official MCP — LLM reads/writes your workspace pages, databases, tasks. Most common uses: meeting-note cleanup, auto-categorising the task DB.

Token required5-min install

Why client-side

A Notion integration token can read/write **anything shared to the integration** — high-sensitivity credential. twinkle-hub does not store it. It lives only in your local Claude Desktop config; the local npx process talks directly to the Notion API.

Prerequisites

Node.js ≥ 18
Notion workspace owner / admin (or have an admin create the integration for you)
MCP-capable client

Get a token

1Go to https://www.notion.so/profile/integrations
2Click + New integration
3Name it (e.g. "Claude MCP"), pick your workspace
4Capabilities: tick Read content (recommended); only tick Update / Insert content if you need writes; do NOT tick user-related permissions
5Save, copy the Internal Integration Token (starts with ntn_)
6Important: on each page/database you want to expose, click ⋯ in the top-right → Connections → add your integration. Without this step the integration sees nothing. Tip: keep an "AI Workspace" section and only connect that.

Install

Claude Desktop (macOS)

~/Library/Application Support/Claude/claude_desktop_config.json

OPENAPI_MCP_HEADERS is a JSON string (escape the quotes). Replace the placeholder with your token.

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer <your_notion_token>\",\"Notion-Version\":\"2022-06-28\"}"
      }
    }
  }
}

Full install doc (GitHub)

First run

Try this prompt

Search my Notion for pages about "meeting notes"

Common tools

API-post-search — full-text search
API-retrieve-a-page — fetch one page
API-retrieve-a-database — fetch DB schema
API-post-page — create page
API-patch-page — edit page properties
API-patch-block-children — add block content

Troubleshooting

Symptom	Fix
Could not find page/database	The page isn't connected to your integration. Add it from Notion UI.
401 Unauthorized	Token wrong or revoked. Check integration settings.
object_not_found on parent_id	Target parent page wasn't shared to the integration
Suspect token leaked	Revoke immediately at https://www.notion.so/profile/integrations and create a new one

Security notes

Integration tokens are partial Notion access — never commit to git, paste in chat, or save to public cloud drives
Create a dedicated integration ("Claude MCP") — don't share across tools
Minimum capabilities: start read-only, watch LLM behaviour, then enable writes
Minimum page scope: maintain a dedicated "AI Workspace" section; only connect that