# Notion MCP Server

A Model Context Protocol server for Notion API integration, providing tools to create, retrieve, and update Notion pages.

## Features

- **Create Page**: Create new pages in databases or as child pages
- **Retrieve Page**: Get page properties and metadata
- **Update Page**: Modify page properties, icons, covers, and archive status
- **Retrieve Page Property**: Get detailed property information with pagination support

## Installation

```bash
cd backend/notion-mcp
npm install
```

## Configuration

Create a `.env` file with your Notion API key:

```env
NOTION_API_KEY=your_notion_integration_token_here
NOTION_VERSION=2022-06-28
PORT=3003
```

### Getting a Notion API Key

1. Go to [Notion Developers](https://developers.notion.com/)
2. Create a new integration
3. Copy the "Internal Integration Token"
4. Share your databases/pages with the integration

## Usage

### STDIO Transport (Development)

```bash
npm run dev:stdio
```

### HTTP Transport (Production)

```bash
npm run dev:http
# or
npm start
```

## Available Tools

### notion_create_page

Creates a new page in Notion.

**Parameters:**
- `parent` (required): Parent page or database ID
- `properties` (required): Page properties matching parent schema
- `children` (optional): Page content as block objects
- `icon` (optional): Page icon (emoji or external URL)
- `cover` (optional): Page cover image

**Example:**
```json
{
  "parent": {
    "type": "database_id",
    "database_id": "d9824bdc-8445-4327-be8b-5b47500af6ce"
  },
  "properties": {
    "Name": {
      "title": [{"text": {"content": "New Page"}}]
    }
  },
  "icon": {
    "type": "emoji",
    "emoji": "📝"
  }
}
```

### notion_retrieve_page

Retrieves a Notion page by ID.

**Parameters:**
- `page_id` (required): The page ID to retrieve
- `filter_properties` (optional): Specific property IDs to return

### notion_update_page

Updates page properties and metadata.

**Parameters:**
- `page_id` (required): The page ID to update
- `properties` (optional): Properties to update
- `in_trash` (optional): Archive/restore the page
- `icon` (optional): Update page icon
- `cover` (optional): Update page cover

### notion_retrieve_page_property

Retrieves detailed property information with pagination.

**Parameters:**
- `page_id` (required): The page ID
- `property_id` (required): The property ID
- `page_size` (optional): Number of items per page (max 100)
- `start_cursor` (optional): Pagination cursor

## Building

```bash
npm run build
```

## Development

```bash
npm run watch  # Watch mode for TypeScript compilation
```

## Client Configuration

For HTTP transport, add to your MCP client config:

```json
{
  "mcpServers": {
    "notion": {
      "url": "http://localhost:3003/mcp"
    }
  }
}
```

For STDIO transport:

```json
{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}
```

## Health Check

When running HTTP transport:

```bash
curl http://localhost:3003/health
```

## Error Handling

The server provides detailed error messages for:
- Missing API keys
- Invalid page/database IDs
- Permission errors
- Malformed requests
- Notion API rate limits

## License

MIT