# Notion MCP Server

Model Context Protocol (MCP) server for the Notion API. Provides comprehensive access to Notion workspaces including pages, databases, blocks, users, comments, and search.

## Features

- **Pages**: Create, read, update, and archive pages
- **Databases**: Query, create, and manage databases with advanced filtering and sorting
- **Blocks**: Retrieve, append, update, and delete blocks
- **Users**: Access workspace user information
- **Comments**: Create and retrieve comments on pages and blocks
- **Search**: Search across all pages and databases
- **Rate Limiting**: Built-in rate limiting (3 req/sec) with retry logic
- **Pagination**: Automatic cursor-based pagination support
- **Type Safety**: Comprehensive TypeScript types for the entire Notion API

## Installation

```bash
npm install
npm run build
```

## Configuration

Set the `NOTION_API_KEY` environment variable:

```bash
export NOTION_API_KEY="your_notion_integration_token"
```

Or create a `.env` file:

```bash
cp .env.example .env
# Edit .env and add your API key
```

### Getting a Notion API Key

1. Go to https://www.notion.so/my-integrations
2. Click "+ New integration"
3. Give it a name and select the workspace
4. Copy the "Internal Integration Token"
5. Share your Notion pages/databases with the integration

## Usage

### Development

```bash
npm run dev
```

### Production

```bash
npm start
```

### With MCP Client

Add to your MCP settings configuration:

```json
{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["/path/to/notion/dist/main.js"],
      "env": {
        "NOTION_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Available Tools

### Pages

- `notion_get_page` - Retrieve a page by ID
- `notion_create_page` - Create a new page
- `notion_update_page` - Update page properties or archive

### Databases

- `notion_get_database` - Get database schema and info
- `notion_query_database` - Query with filters and sorts
- `notion_create_database` - Create a new database

### Blocks

- `notion_get_block` - Get a block by ID
- `notion_get_block_children` - Get child blocks
- `notion_append_block_children` - Add blocks to a parent
- `notion_delete_block` - Archive a block

### Users

- `notion_get_user` - Get user info
- `notion_list_users` - List all workspace users

### Comments

- `notion_create_comment` - Add a comment
- `notion_list_comments` - Get comments for a block

### Search

- `notion_search` - Search pages and databases

## Architecture

### Type System (`src/types/index.ts`)

Comprehensive TypeScript definitions including:

- All block types as discriminated unions
- All property types (title, rich_text, number, select, etc.)
- User, Page, Database, Comment types
- Filter and Sort builders
- Pagination types
- Branded ID types for type safety

### Client (`src/clients/notion.ts`)

Axios-based HTTP client with:

- Bearer token authentication
- Automatic rate limiting (3 req/sec)
- Exponential backoff retry logic
- Cursor-based pagination helpers
- Async generator support for large datasets

### Server (`src/server.ts`)

MCP server implementation with:

- Lazy-loaded tool handlers
- Structured error handling
- JSON schema validation
- Comprehensive tool definitions

### Entry Point (`src/main.ts`)

- Environment validation
- Stdio transport setup
- Graceful shutdown handling
- Error logging

## Development

```bash
# Type check
npm run typecheck

# Build
npm run build

# Run in dev mode
npm run dev
```

## License

MIT

## Contributing

Contributions welcome! Please ensure:

- TypeScript compiles with zero errors
- Follow existing code style
- Add tests for new features
- Update documentation