# 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](https://www.notion.so/my-integrations).
- Share target pages or databases with your Notion integration in Notion UI.

### 2. Installation
```bash
cd /Users/xavier.villarroel/GitHub/cs-ai-notion-mcp
npm install
```

### 3. Environment Configuration
Copy `.env.example` to `.env` and set your key:
```bash
cp .env.example .env
```
Edit `.env`:
```env
NOTION_API_KEY=secret_your_actual_notion_api_token
```

## Running the Server

### Local Execution (stdio)
```bash
npm start
```

### Testing with MCP Inspector
```bash
npx @modelcontextprotocol/inspector node index.mjs
```

### Adding to MCP Config (e.g. Claude Desktop or Antigravity)
```json
{
  "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