Skip to main content
Glama
cs-ai-notion-mcp

cs-ai-notion-mcp

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.

Related MCP server: Notion MCP Server

Setup & Installation

1. Prerequisites

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

Available Tools

7 tools
append_blocksD

Inputs: block_id (required), text_lines (required).

create_pageD

Inputs: title (required), parent_id (required), parent_type, content_body.

delete_pageD

Inputs: page_id (required).

get_pageD

Inputs: page_id (required).

get_page_blocksD

Inputs: block_id (required), page_size.

search_pagesD

Inputs: query, filter_type.

update_pageD

Inputs: page_id (required), archived.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.1/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool focuses on a distinct operation: searching, retrieving, creating, updating, deleting pages, plus fetching and appending blocks. There is no overlap in purpose, and the actions are easily distinguishable.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (e.g., search_pages, create_page, get_page_blocks). The pattern is uniform and predictable.

    Tool Count5/5

    With 7 tools, the set is well-scoped for a Notion page management server. Each tool covers a core operation without redundancy or bloat.

    Completeness4/5

    The domain covers basic page lifecycle (CRUD + search) and block interactions (get/append). Minor gaps exist (e.g., update/delete blocks), but the core workflows for page management are well covered.

    Related MCP Connectors

    Related MCP Servers