cs-ai-notion-mcp

A custom Model Context Protocol (MCP) server for Notion providing full CRUD (Create, Read, Update, Delete) capabilities over Notion pages, databases, and content blocks. Built using FastMCP (@modelcontextprotocol/sdk) and the official Notion JavaScript SDK (@notionhq/client).

Features

• 🔍 search_pages: Search pages or databases in your Notion workspace.
• 📖 get_page: Retrieve metadata and properties for a specific page.
• 📝 create_page: Create new pages under existing pages or database entries.
• ✏️ update_page: Update page properties or toggle archive status.
• 🧱 get_page_blocks: Read child content blocks (paragraphs, lists, headings) from a page.
• ➕ append_blocks: Append new content blocks to a page or block.
• 🗑️ delete_page: Archive/delete a page from Notion.

Setup & Installation

1. Prerequisites

• Node.js >= 18
• A Notion Integration Token (NOTION_API_KEY) created at https://www.notion.so/my-integrations.
• Share target pages or databases with your Notion integration in Notion UI.

2. Installation

cd /Users/xavier.villarroel/GitHub/cs-ai-notion-mcp
npm install

3. Environment Configuration

Copy .env.example to .env and set your key:

cp .env.example .env

Edit .env:

NOTION_API_KEY=secret_your_actual_notion_api_token

Running the Server

Local Execution (stdio)

npm start

Testing with MCP Inspector

npx @modelcontextprotocol/inspector node index.mjs

Adding to MCP Config (e.g. Claude Desktop or Antigravity)

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["/Users/xavier.villarroel/GitHub/cs-ai-notion-mcp/index.mjs"],
      "env": {
        "NOTION_API_KEY": "secret_your_actual_notion_api_token"
      }
    }
  }
}

Code Architecture

The codebase follows strict project standards with 4 clearly delineated sections in index.mjs:

1. Import Section: Module dependencies (@modelcontextprotocol/sdk, @notionhq/client, zod, dotenv).
2. Functions Section: Low-level Notion API operations.
3. Handler Section: MCP tool definitions and stdio server initialization.
4. Comments Section: Exhaustive documentation for LLM code comprehension and testing.

License

MIT