Notion Plugin

Full-featured Notion integration for OpenCode, providing comprehensive access to databases, pages, blocks, users, and comments through the official Notion API.

Features

• Search: Search across all accessible pages and databases
• Databases: List, query, and get schema information
• Pages: Create, read, update, archive, and restore pages
• Blocks: Read page content, append blocks, delete blocks
• Users: List workspace users and get user details
• Comments: Read and add comments to pages

Setup

1. Create a Notion Integration

1. Go to https://www.notion.so/my-integrations
2. Click New integration
3. Give it a name (e.g., "OpenCode Integration")
4. Select your workspace
5. Under Capabilities, ensure you have:
   • Read content
   • Update content
   • Insert content
   • Read comments
   • Insert comments
   • Read user information
6. Click Submit
7. Copy the Internal Integration Token (starts with secret_)

2. Configure Environment

Add to your .env file:

NOTION_INTERNAL_INTEGRATION_SECRET=secret_your_token_here

3. Share Pages/Databases with Your Integration

Important: Your integration can only access pages and databases explicitly shared with it.

1. Open a page or database in Notion
2. Click the ... menu in the top right
3. Select Connections (or Add connections)
4. Find and add your integration

Available Tools

Connection & Search

| Tool | Description | |------|-------------| | notion-test-connection | Test connection and get workspace info | | notion-search | Search across all pages and databases |

Databases

| Tool | Description | |------|-------------| | notion-list-databases | List all accessible databases | | notion-get-database | Get database schema and properties | | notion-query-database | Query database with filters and sorting |

Pages

| Tool | Description | |------|-------------| | notion-get-page | Get page properties and metadata | | notion-get-page-content | Get all blocks (content) from a page | | notion-create-page | Create a new page in a database or as child | | notion-update-page | Update page properties | | notion-archive-page | Archive (soft delete) a page | | notion-restore-page | Restore an archived page |

Blocks

| Tool | Description | |------|-------------| | notion-get-block-children | Get child blocks of a block | | notion-append-blocks | Add content blocks to a page | | notion-delete-block | Delete a block |

Users

| Tool | Description | |------|-------------| | notion-list-users | List all workspace users | | notion-get-user | Get user details |

Comments

| Tool | Description | |------|-------------| | notion-get-comments | Get comments on a page or block | | notion-add-comment | Add a comment to a page |

Usage Examples

Search for Pages

Search for all pages containing "meeting notes"

Query a Database

Query my tasks database and show items where Status is "In Progress"

The filter follows Notion's filter format:

{"property": "Status", "status": {"equals": "In Progress"}}

Create a Page in a Database

Create a new task called "Review PRs" in my tasks database with status "To Do"

Add Content to a Page

Add a paragraph "Project kickoff meeting scheduled for Monday" to page abc123

Block types supported:

• paragraph - Regular text
• heading_1, heading_2, heading_3 - Headers
• bulleted_list_item, numbered_list_item - Lists
• to_do - Checkboxes with checked property
• quote - Blockquotes
• callout - Callout boxes with icon property
• code - Code blocks with language property
• divider - Horizontal lines
• toggle - Collapsible sections

Get Page Content

Show me the contents of page abc123

Filter Examples for Database Queries

Status Filter

{"property": "Status", "status": {"equals": "Done"}}

Text Contains

{"property": "Name", "rich_text": {"contains": "project"}}

Checkbox

{"property": "Completed", "checkbox": {"equals": true}}

Date Filter

{"property": "Due Date", "date": {"on_or_before": "2024-12-31"}}

Compound Filters (AND)

{
  "and": [
    {"property": "Status", "status": {"equals": "In Progress"}},
    {"property": "Priority", "select": {"equals": "High"}}
  ]
}

Compound Filters (OR)

{
  "or": [
    {"property": "Status", "status": {"equals": "Done"}},
    {"property": "Status", "status": {"equals": "Archived"}}
  ]
}

Property Update Examples

Update Status

{"Status": {"status": {"name": "Done"}}}

Update Text

{"Description": {"rich_text": [{"text": {"content": "Updated description"}}]}}

Update Checkbox

{"Completed": {"checkbox": true}}

Update Select

{"Priority": {"select": {"name": "High"}}}

Update Multi-Select

{"Tags": {"multi_select": [{"name": "urgent"}, {"name": "bug"}]}}

Update Date

{"Due Date": {"date": {"start": "2024-12-31"}}}

Update Number

{"Score": {"number": 95}}

Troubleshooting

"Object not found" Error

• Make sure the page/database is shared with your integration
• Verify the ID is correct (copy from Notion URL or use search)

"Unauthorized" Error

• Check your NOTION_INTERNAL_INTEGRATION_SECRET is set correctly
• Ensure the token hasn't been revoked

Can't See Pages/Databases

• You must explicitly share each page/database with your integration
• Child pages inherit parent permissions, but databases must be shared individually

Filter Not Working

• Use notion-get-database to see available property names and types
• Property names are case-sensitive
• Check the filter syntax matches the property type

Links

• Notion API Documentation
• Notion SDK for JavaScript
• Filter Documentation