# notion-mcp

A Notion MCP server using OAuth2 bearer token auth via the Dedalus framework.

## Features

This MCP server provides tools to interact with the Notion API:

### User Tools
- `notion_get_user` - Retrieve a specific user by ID
- `notion_list_users` - List all users in the workspace
- `notion_get_self` - Get the authenticated bot user's information

### Search Tools
- `notion_search` - Search pages and databases by title

### Block Tools
- `notion_get_block` - Retrieve a block by ID
- `notion_get_block_children` - Get child blocks of a parent
- `notion_append_block_children` - Append new blocks to a parent
- `notion_update_block` - Update a block's content
- `notion_delete_block` - Delete (archive) a block

### Page Tools
- `notion_get_page` - Get a page's metadata and properties
- `notion_get_page_property` - Get a specific property from a page
- `notion_create_page` - Create a new page
- `notion_update_page` - Update a page's properties

### Comment Tools
- `notion_get_comments` - Retrieve comments from a page or block
- `notion_create_comment` - Create a comment on a page

### Database Tools
- `notion_query_database` - Query a database with filters and sorts
- `notion_get_database` - Get database metadata and schema
- `notion_update_database` - Update database properties
- `notion_create_database` - Create a new database

## Installation

```bash
# Clone the repository
git clone https://github.com/dedalus-labs/notion-mcp.git
cd notion-mcp

# Install dependencies with uv
uv sync
```

## Configuration

Copy `.env.example` to `.env` and configure:

```bash
cp .env.example .env
```

### OAuth Configuration

The Notion API requires OAuth2 authentication. The access token is provided at runtime via Dedalus credential exchange.

Required OAuth scopes depend on your use case:
- Read content: Basic integration capabilities
- Insert content: Create pages and blocks
- Update content: Modify existing content
- Read user information (without email): List users

## Usage

### Running Locally

```bash
cd notion-mcp
uv sync
uv run python src/main.py
```

The server will start on port 8080.

### With Dedalus Platform

In your chat, reference the server with `@notion-mcp` followed by your instructions:

```
@notion-mcp Search for all pages containing "meeting notes"
```

```
@notion-mcp Create a new page titled "Project Plan" in my workspace
```

## Development

### Running Tests

```bash
uv run pytest
```

### Linting

```bash
uv run ruff check src/
uv run ruff format src/
```

## License

MIT License - see [LICENSE](LICENSE) for details.