Notion Connector

SKILL.md

---
name: notion-connector
description: >
  Access Notion workspace with managed OAuth to create, read, update pages, databases, and blocks using the Notion API.
  Use when the user wants to interact with Notion pages, databases, search workspace, or manage Notion content.
  Keywords: notion, pages, database, workspace, blocks, notes, wiki.
metadata:
  polly:
    polly_managed_connector: true
    auth:
      - env: NOTION_ACCESS_TOKEN
        type: oauth2
        integration_id: notion
        description: Notion OAuth access
        scopes:
          - read_content
          - update_content
          - insert_content
        required_capabilities:
          - read_content
          - update_content
          - insert_content
    primaryEnv: NOTION_ACCESS_TOKEN
---

# Notion Connector

Access your Notion workspace through the Notion API with Polly-managed OAuth authentication.

---

## Prerequisites

### Authentication

This skill uses **Polly-managed OAuth2 authentication**. The access token is automatically managed and refreshed by Polly's auth system via the `NOTION_ACCESS_TOKEN` environment variable.

**No manual token refresh is needed** — Polly handles token refresh automatically when needed.

On first use, if not connected, call:
```
manage_auth(action="connect", integration_id="notion", auth_env="NOTION_ACCESS_TOKEN")
```

---

## Script

All API calls go through `scripts/notion_api.py`:

```bash
python3 /home/polly/skills/installed/notion-connector/scripts/notion_api.py <command> [args]
```

---

## Commands

### Search

**Search workspace:**
```bash
python3 scripts/notion_api.py search "query text" --limit 10
```

**Search by type:**
```bash
python3 scripts/notion_api.py search "query" --filter page
# --filter options: page, database
```

### Pages

**Get page:**
```bash
python3 scripts/notion_api.py page get <page_id>
```

**Create page:**
```bash
python3 scripts/notion_api.py page create --parent <page_id> --title "Title" --content "Content"
```

**Update page:**
```bash
python3 scripts/notion_api.py page update <page_id> --title "New Title"
```

### Databases

**Query database:**
```bash
python3 scripts/notion_api.py database query <database_id> --limit 10
```

**Get database:**
```bash
python3 scripts/notion_api.py database get <database_id>
```

**Create database page:**
```bash
python3 scripts/notion_api.py database create-page <database_id> --properties '{"Name": {"title": [{"text": {"content": "Item"}}]}}'
```

### User

**Get current user:**
```bash
python3 scripts/notion_api.py user me
```

**List users:**
```bash
python3 scripts/notion_api.py user list
```

---

## Notes

- Access tokens are **automatically refreshed by Polly's auth system**
- The LLM never directly accesses refresh tokens — they are managed securely by Polly
- The `NOTION_ACCESS_TOKEN` environment variable is injected automatically when the skill runs
- Uses Notion API v1
- Page IDs can be extracted from Notion URLs