mirror of
https://github.com/open-webui/docs.git
synced 2025-12-12 07:29:49 +07:00
Merge pull request #854 from silentoplayz/notion-mcp-revision
docs: Notion MCP refac
This commit is contained in:
Tim Baek
@@ -19,87 +19,15 @@ This integration utilizes the official Notion MCP server, which specializes in *
|
|||||||
This tutorial is a community contribution and is not supported by the Open WebUI team. It serves as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the [contributing tutorial](/tutorials/tips/contributing-tutorial/).
|
This tutorial is a community contribution and is not supported by the Open WebUI team. It serves as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the [contributing tutorial](/tutorials/tips/contributing-tutorial/).
|
||||||
:::
|
:::
|
||||||
|
|
||||||
## Prerequisites
|
## Method 1: Streamable HTTP (Recommended)
|
||||||
|
|
||||||
Regardless of the connection method chosen, you must first create an internal integration within Notion.
|
|
||||||
|
|
||||||
### 1. Create Internal Integration
|
|
||||||
1. Navigate to [Notion My Integrations](https://www.notion.so/my-integrations).
|
|
||||||
2. Click the **+ New integration** button.
|
|
||||||
3. Fill in the required fields:
|
|
||||||
* **Integration Name:** Give it a recognizable name (e.g., "Open WebUI MCP").
|
|
||||||
* **Associated workspace:** Select the specific workspace you want to connect.
|
|
||||||
* **Type:** Select **Internal**.
|
|
||||||
* **Logo:** Uploading a logo is optional but helps identify the integration.
|
|
||||||
4. Click **Save**.
|
|
||||||
|
|
||||||
:::info Important: Integration Type
|
|
||||||
You **must** select **Internal** for the integration type. Public integrations require a different OAuth flow that is not covered in this guide.
|
|
||||||
:::
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### 2. Configure Capabilities & Copy Secret
|
|
||||||
Once saved, you will be directed to the configuration page.
|
|
||||||
1. **Copy Secret:** Locate the **Internal Integration Secret** field. Click **Show** and copy this key. You will need it for Open WebUI.
|
|
||||||
2. **Review Capabilities:** Ensure the following checkboxes are selected under the "Capabilities" section:
|
|
||||||
* ✅ **Read content**
|
|
||||||
* ✅ **Update content**
|
|
||||||
* ✅ **Insert content**
|
|
||||||
* *(Optional)* Read user information including email addresses.
|
|
||||||
3. Click **Save changes** if you modified any capabilities.
|
|
||||||
|
|
||||||
:::warning Security: Risk to Workspace Data
|
|
||||||
While the Notion MCP server limits the scope of the API (e.g., databases cannot be deleted), exposing your workspace to LLMs carries a **non-zero risk** to your data.
|
|
||||||
|
|
||||||
**Security-conscious users** can create a safer, **Read-Only** integration by unchecking **Update content** and **Insert content** in this step. The AI will be able to search and answer questions based on your notes but will be physically unable to modify or create pages.
|
|
||||||
:::
|
|
||||||
|
|
||||||
:::danger Secret Safety
|
|
||||||
Your **Internal Integration Secret** allows access to your Notion data. Treat it like a password. Do not share it or commit it to public repositories.
|
|
||||||
:::
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### 3. Grant Page Access
|
|
||||||
|
|
||||||
:::danger Critical Step: Permissions
|
|
||||||
By default, your new integration has **zero access** to your workspace. It cannot see *any* pages until you explicitly invite it. If you skip this step, the AI will return "Object not found" errors.
|
|
||||||
:::
|
|
||||||
|
|
||||||
You can grant access centrally or on a per-page basis.
|
|
||||||
|
|
||||||
#### Method A: Centralized Access (Recommended)
|
|
||||||
Still in the Notion Integration dashboard:
|
|
||||||
1. Click the **Access** tab (next to Configuration).
|
|
||||||
2. Click the **Edit access** button.
|
|
||||||
3. A modal will appear allowing you to select specific pages or "Select all" top-level pages.
|
|
||||||
4. Check the pages you want the AI to read/edit and click **Save**.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
#### Method B: Page-Level Access
|
|
||||||
1. Go to a specific Notion Page or Database you want the AI to access.
|
|
||||||
2. Click the **...** (three dots) menu in the top right corner of the page.
|
|
||||||
3. Select **Connections** (in the "Add connections" section).
|
|
||||||
4. Search for your integration name (e.g., "Open WebUI MCP") and click **Connect**.
|
|
||||||
5. *You must repeat this for every root page or database you want the AI to be able to search or edit.*
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
There are two ways to connect Notion. We recommend **Streamable HTTP** for the easiest setup experience (OAuth), or **Local CLI** for advanced control using your integration token.
|
|
||||||
|
|
||||||
The **Streamable HTTP** method is natively supported and recommended for most users for the easiest setup experience (OAuth).
|
|
||||||
|
|
||||||
To run the server locally (using Docker or Node.js), you must use the **MCPO Bridge**.
|
|
||||||
|
|
||||||
<Tabs>
|
|
||||||
<TabItem value="http" label="Method 1: Streamable HTTP (Recommended)" default>
|
|
||||||
This method connects directly to Notion's hosted MCP endpoint (`https://mcp.notion.com/mcp`). It utilizes standard OAuth and is **natively supported** by Open WebUI without extra containers.
|
This method connects directly to Notion's hosted MCP endpoint (`https://mcp.notion.com/mcp`). It utilizes standard OAuth and is **natively supported** by Open WebUI without extra containers.
|
||||||
|
|
||||||
### Quick Setup via Import
|
:::info Preferred Method
|
||||||
|
**Streamable HTTP** is preferred for its simplicity and enhanced security. It handles authentication via Notion's official OAuth flow, meaning you do not need to manually manage secrets or integration tokens.
|
||||||
|
:::
|
||||||
|
|
||||||
|
### 1. Configure Tool
|
||||||
You can automatically prefill the connection settings by importing the JSON configuration below.
|
You can automatically prefill the connection settings by importing the JSON configuration below.
|
||||||
|
|
||||||
1. Navigate to **Admin Panel > Settings > External Tools**.
|
1. Navigate to **Admin Panel > Settings > External Tools**.
|
||||||
@@ -126,24 +54,49 @@ To run the server locally (using Docker or Node.js), you must use the **MCPO Bri
|
|||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
5. **Enter Key:** Paste your **Internal Integration Secret** (starts with `secret_`) into the "Key" field.
|
5. **Register:** Click the **Register Client** button (next to the Auth dropdown).
|
||||||
6. **Register:** Click the **Register Client** button (next to the Auth dropdown).
|
6. Click **Save**.
|
||||||
7. Click **Save**.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
</TabItem>
|
### 2. Authenticate & Grant Access
|
||||||
|
Once the tool is added, you must authenticate to link your specific workspace.
|
||||||
|
|
||||||
<TabItem value="mcpo" label="Method 2: Self-Hosted via MCPO (Advanced)">
|
1. Open any chat window.
|
||||||
Direct local execution (stdio) of MCP servers is not natively supported in Open WebUI. To run the Notion MCP server using `docker` or `npx` within your infrastructure, you must use **MCPO**.
|
2. Click the **+** (Plus) button in the chat input bar.
|
||||||
|
3. Navigate to **Integrations > Tools**.
|
||||||
|
4. Toggle the **Notion** switch to **ON**.
|
||||||
|
|
||||||
MCPO acts as a bridge, running your local commands and exposing them to Open WebUI via a local HTTP endpoint.
|
|
||||||
|
|
||||||
### Step 1: Deploy MCPO
|
5. **Authorize:** You will be redirected to a "Connect with Notion MCP" screen.
|
||||||
Follow the installation instructions in the [MCPO Repository](https://github.com/open-webui/mcpo) to get it running (usually done via Docker).
|
* Ensure the correct **Workspace** is selected in the dropdown.
|
||||||
|
* Click **Continue**.
|
||||||
|
|
||||||
### Step 2: Configure MCPO
|
:::note Security: Frequent Re-authentication
|
||||||
Configure your MCPO instance to run the Notion server using one of the runtimes below. Add the appropriate JSON block to your `mcpo-config.json` file.
|
For security reasons, Notion's OAuth session may expire after a period of inactivity or if you restart your Open WebUI instance. If this happens, you will see a `Failed to connect to MCP server 'ntn'` error.
|
||||||
|
|
||||||
|
This is **intended behavior** by Notion to keep your workspace secure. To refresh your session, revisit the steps above to complete the "Connect with Notion MCP" authorization flow again.
|
||||||
|
:::
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Method 2: Self-Hosted via MCPO (Advanced)
|
||||||
|
|
||||||
|
This method is for advanced users who prefer to run the MCP server locally within their own infrastructure using **MCPO**. Unlike Streamable HTTP, this method requires you to manually manage your own credentials.
|
||||||
|
|
||||||
|
Direct local execution (stdio) of MCP servers is not natively supported in Open WebUI. To run the Notion MCP server locally (using Docker or Node.js) within your infrastructure, you must use **MCPO** to bridge the connection.
|
||||||
|
|
||||||
|
:::info Prerequisites
|
||||||
|
To use this method, you must first create an internal integration to obtain a **Secret Key**. Please complete the **[Creating an Internal Integration](#creating-an-internal-integration)** section below before proceeding with the configuration steps here.
|
||||||
|
:::
|
||||||
|
|
||||||
|
### 1. Configure MCPO
|
||||||
|
Follow the installation instructions in the [MCPO Repository](https://github.com/open-webui/mcpo) to get it running. Configure your MCPO instance to run the Notion server using one of the runtimes below by adding the JSON block to your `mcpo-config.json` file.
|
||||||
|
|
||||||
|
**Note:** Replace `secret_YOUR_KEY_HERE` with the secret obtained from the [Creating an Internal Integration](#creating-an-internal-integration) section.
|
||||||
|
|
||||||
<Tabs>
|
<Tabs>
|
||||||
<TabItem value="npx" label="Node (npx)" default>
|
<TabItem value="npx" label="Node (npx)" default>
|
||||||
@@ -167,7 +120,7 @@ To run the server locally (using Docker or Node.js), you must use the **MCPO Bri
|
|||||||
```
|
```
|
||||||
</TabItem>
|
</TabItem>
|
||||||
<TabItem value="docker" label="Docker">
|
<TabItem value="docker" label="Docker">
|
||||||
This configuration runs the server as an isolated container.
|
This configuration uses the official Docker image.
|
||||||
|
|
||||||
```json title="mcpo-config.json"
|
```json title="mcpo-config.json"
|
||||||
{
|
{
|
||||||
@@ -192,7 +145,7 @@ To run the server locally (using Docker or Node.js), you must use the **MCPO Bri
|
|||||||
</TabItem>
|
</TabItem>
|
||||||
</Tabs>
|
</Tabs>
|
||||||
|
|
||||||
### Step 3: Connect Open WebUI
|
### 2. Connect Open WebUI
|
||||||
Once MCPO is running and configured with Notion:
|
Once MCPO is running and configured with Notion:
|
||||||
|
|
||||||
1. Navigate to **Admin Panel > Settings > External Tools**.
|
1. Navigate to **Admin Panel > Settings > External Tools**.
|
||||||
@@ -219,40 +172,82 @@ To run the server locally (using Docker or Node.js), you must use the **MCPO Bri
|
|||||||
]
|
]
|
||||||
```
|
```
|
||||||
5. Click **Save**.
|
5. Click **Save**.
|
||||||
</TabItem>
|
|
||||||
</Tabs>
|
|
||||||
|
|
||||||
## Enabling the Tool
|
---
|
||||||
|
|
||||||
After configuring the connection in the Admin Panel, you must enable the tool for the AI to use it.
|
## Creating an Internal Integration
|
||||||
|
|
||||||
:::tip Initial Authentication
|
Required for **Method 2**, creating an internal integration within Notion ensures you have the necessary credentials and permission scopes readily available.
|
||||||
If you are using **Method 1 (Streamable HTTP)**, you must perform the On-Demand step below at least once to trigger the OAuth flow. If using **Method 2 (MCPO)**, authentication is handled by the API key in your configuration.
|
|
||||||
|
### 1. Create Integration
|
||||||
|
1. Navigate to **[Notion My Integrations](https://www.notion.so/my-integrations)**.
|
||||||
|
2. Click the **+ New integration** button.
|
||||||
|
3. Fill in the required fields:
|
||||||
|
* **Integration Name:** Give it a recognizable name (e.g., "Open WebUI MCP").
|
||||||
|
* **Associated workspace:** Select the specific workspace you want to connect.
|
||||||
|
* **Type:** Select **Internal**.
|
||||||
|
* **Logo:** Uploading a logo is optional but helps identify the integration.
|
||||||
|
4. Click **Save**.
|
||||||
|
|
||||||
|
:::info Important: Integration Type
|
||||||
|
You **must** select **Internal** for the integration type. Public integrations require a different OAuth flow that is not covered in this guide.
|
||||||
:::
|
:::
|
||||||
|
|
||||||
### Option 1: On-Demand (Per Chat)
|
|
||||||
|
|
||||||
1. Open a new chat.
|
### 2. Configure Capabilities & Copy Secret
|
||||||
2. Click the **+** (Plus) button in the chat input bar.
|
Once saved, you will be directed to the configuration page.
|
||||||
3. Navigate to **Integrations > Tools**.
|
1. **Copy Secret:** Locate the **Internal Integration Secret** field. Click **Show** and copy this key. You will need it for MCPO configuration.
|
||||||
4. Toggle the **Notion** switch to **ON**.
|
2. **Review Capabilities:** Ensure the following checkboxes are selected under the "Capabilities" section:
|
||||||
|
* ✅ **Read content**
|
||||||
|
* ✅ **Update content**
|
||||||
|
* ✅ **Insert content**
|
||||||
|
* *(Optional)* Read user information including email addresses.
|
||||||
|
3. Click **Save changes** if you modified any capabilities.
|
||||||
|
|
||||||
|
:::warning Security: Risk to Workspace Data
|
||||||
|
While the Notion MCP server limits the scope of the API (e.g., databases cannot be deleted), exposing your workspace to LLMs carries a **non-zero risk**.
|
||||||
|
|
||||||
5. **Authorize:** (Method 1 Only) You will be redirected to a "Connect with Notion MCP" screen.
|
**Security-conscious users** can create a safer, **Read-Only** integration by unchecking **Update content** and **Insert content**. The AI will be able to search and answer questions based on your notes but will be physically unable to modify or create pages.
|
||||||
* Ensure the correct **Workspace** (the one you configured in step 1) is selected in the dropdown.
|
|
||||||
* Click **Continue**.
|
|
||||||
|
|
||||||
:::note Security: Frequent Re-authentication
|
|
||||||
For security reasons, Notion's OAuth session may expire after a period of inactivity or if you restart your Open WebUI instance. If this happens, you will see a `Failed to connect to MCP server 'ntn'` error.
|
|
||||||
|
|
||||||
This is **intended behavior** by Notion to keep your workspace secure. To refresh your session, revist steps 1-4 of this option to complete the "Connect with Notion MCP" authorization flow again, which will refresh your session.
|
|
||||||
:::
|
:::
|
||||||
|
|
||||||
|
:::danger Secret Safety
|
||||||
|
Your **Internal Integration Secret** allows access to your Notion data. Treat it like a password. Do not share it or commit it to public repositories.
|
||||||
|
:::
|
||||||
|
|
||||||
### Option 2: Always On (Model Default)
|
|
||||||
You can configure a specific model to have Notion access enabled by default for every conversation.
|
|
||||||
|
### 3. Grant Page Access (Manual)
|
||||||
|
|
||||||
|
:::danger Critical Step: Permissions
|
||||||
|
By default, your new internal integration has **zero access** to your workspace. It cannot see *any* pages until you explicitly invite it. If you skip this step, the AI will return "Object not found" errors.
|
||||||
|
:::
|
||||||
|
|
||||||
|
You can grant access centrally or on a per-page basis.
|
||||||
|
|
||||||
|
#### Method A: Centralized Access (Recommended)
|
||||||
|
Still in the Notion Integration dashboard:
|
||||||
|
1. Click the **Access** tab (next to Configuration).
|
||||||
|
2. Click the **Edit access** button.
|
||||||
|
3. A modal will appear allowing you to select specific pages or "Select all" top-level pages.
|
||||||
|
4. Check the pages you want the AI to read/edit and click **Save**.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### Method B: Page-Level Access
|
||||||
|
1. Go to a specific Notion Page or Database you want the AI to access.
|
||||||
|
2. Click the **...** (three dots) menu in the top right corner of the page.
|
||||||
|
3. Select **Connections** (in the "Add connections" section).
|
||||||
|
4. Search for your integration name (e.g., "Open WebUI MCP") and click **Connect**.
|
||||||
|
5. *You must repeat this for every root page or database you want the AI to be able to search or edit.*
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Configuration: Always On (Optional)
|
||||||
|
|
||||||
|
By default, users must toggle the tool **ON** in the chat menu. You can configure a specific model to have Notion access enabled by default for every conversation.
|
||||||
|
|
||||||
1. Go to **Workspace > Models**.
|
1. Go to **Workspace > Models**.
|
||||||
2. Click the **pencil icon** to edit a model.
|
2. Click the **pencil icon** to edit a model.
|
||||||
@@ -260,7 +255,7 @@ You can configure a specific model to have Notion access enabled by default for
|
|||||||
4. Check the box for **Notion**.
|
4. Check the box for **Notion**.
|
||||||
5. Click **Save & Update**.
|
5. Click **Save & Update**.
|
||||||
|
|
||||||
## Best Practice: Create a Notion Agent
|
## Building a Specialized Notion Agent
|
||||||
|
|
||||||
For the most reliable experience, we recommend creating a dedicated "Notion Assistant" model. This allows you to provide a specialized **System Prompt**, a helpful **Knowledge Base**, and quick-start **Prompt Suggestions** that teaches the model how to navigate Notion's structure.
|
For the most reliable experience, we recommend creating a dedicated "Notion Assistant" model. This allows you to provide a specialized **System Prompt**, a helpful **Knowledge Base**, and quick-start **Prompt Suggestions** that teaches the model how to navigate Notion's structure.
|
||||||
|
|
||||||
@@ -335,7 +330,6 @@ You are the Notion Workspace Manager, an intelligent agent connected directly to
|
|||||||
```
|
```
|
||||||
</details>
|
</details>
|
||||||
|
|
||||||
|
|
||||||
7. **Attach Knowledge Base:**
|
7. **Attach Knowledge Base:**
|
||||||
* In the **Knowledge** section, click **Select Knowledge**.
|
* In the **Knowledge** section, click **Select Knowledge**.
|
||||||
* In the modal that appears, find and select the **Notion MCP Docs** knowledge base you created in Step 1.
|
* In the modal that appears, find and select the **Notion MCP Docs** knowledge base you created in Step 1.
|
||||||
@@ -343,7 +337,7 @@ You are the Notion Workspace Manager, an intelligent agent connected directly to
|
|||||||
:::warning Performance Tuning
|
:::warning Performance Tuning
|
||||||
While the knowledge base helps the model understand Notion's capabilities, injecting large amounts of documentation can sometimes interfere with tool calling on smaller models (overloading the context).
|
While the knowledge base helps the model understand Notion's capabilities, injecting large amounts of documentation can sometimes interfere with tool calling on smaller models (overloading the context).
|
||||||
|
|
||||||
If you notice the model failing to call tools correctly or hallucinating parameters, **detach the knowledge base** and rely solely on the System Prompt provided above or use your own custom system prompt.
|
If you notice the model failing to call tools correctly or hallucinating parameters, **detach the knowledge base** and rely solely on the System Prompt provided above.
|
||||||
:::
|
:::
|
||||||
|
|
||||||
8. **Add Prompt Suggestions:**
|
8. **Add Prompt Suggestions:**
|
||||||
@@ -362,99 +356,15 @@ Under the **Prompts** section, click the **+** button to add a few helpful start
|
|||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Supported Tools & Usage
|
## Supported Tools
|
||||||
|
|
||||||
Once enabled, the model will have access to a powerful suite of tools to manage your Notion workspace. The server automatically handles converting Notion's block-based structure into Markdown for the AI, and converts the AI's Markdown back into Notion blocks.
|
|
||||||
|
|
||||||
:::tip Workflow Best Practice
|
:::tip Workflow Best Practice
|
||||||
LLMs cannot "browse" Notion like a human. For most actions, the model first needs to know the **Page ID or URL**. Always ask the model to **search** for a page first before asking it to read or modify it.
|
LLMs cannot "browse" Notion like a human. For most actions, the model first needs to know the **Page ID or URL**. Always ask the model to **search** for a page first before asking it to read or modify it.
|
||||||
:::
|
:::
|
||||||
|
|
||||||
## 🔎 Search & Retrieval
|
This integration supports a wide range of tools for searching, reading, creating, and updating Notion pages and databases.
|
||||||
|
|
||||||
- **`notion-search`** – Full‑text / metadata search across Notion (and linked tools)
|
For a complete list of available tools, their descriptions, and specific usage examples, please refer to the **[official Notion MCP documentation](https://developers.notion.com/docs/mcp-supported-tools)**.
|
||||||
- **Input:** query string (e.g., `ready for dev`)
|
|
||||||
- **Returns:** list of object IDs + brief metadata
|
|
||||||
- **Prompt example:** “Find all project pages that mention **‘ready for dev’**.”
|
|
||||||
- **Note:** IDs returned here are required for almost every other command.
|
|
||||||
|
|
||||||
- **`notion-fetch`** *(aka `read-page`)* – Pull a page or database content by URL or ID
|
|
||||||
- **Input:** page/database URL **or** ID
|
|
||||||
- **Returns:** Markdown‑formatted content of the page/database
|
|
||||||
- **Prompt example:** “What are the product requirements from this ticket `https://notion.so/page-url`?”
|
|
||||||
- **Note:** Gives you a clean Markdown view, ready for further processing.
|
|
||||||
|
|
||||||
## 🛠️ Content Management
|
|
||||||
|
|
||||||
- **`notion-create-pages`** – Create a brand‑new page
|
|
||||||
- **Input:** parent page ID, title, property map, body (Markdown format)
|
|
||||||
- **Returns:** new page ID & URL
|
|
||||||
- **Prompt example:** “Create a meeting‑notes page for today’s stand‑up with action items.”
|
|
||||||
- **Key:** **Parent page ID is mandatory**.
|
|
||||||
|
|
||||||
- **`notion-update-page`** – Patch a page’s **properties** (status, tags, dates, etc.)
|
|
||||||
- **Input:** page ID + property map
|
|
||||||
- **Returns:** updated page object
|
|
||||||
- **Prompt example:** “Change the status of this task from **‘In Progress’** to **‘Complete’**.”
|
|
||||||
- **Key:** Does **not** edit the page’s body blocks.
|
|
||||||
|
|
||||||
- **`notion-append-block`** – Add a block (text, checklist, heading, etc.) to the end of a page
|
|
||||||
- **Input:** page ID + block payload (JSON format)
|
|
||||||
- **Returns:** updated page version
|
|
||||||
- **Prompt example:** “Add a checklist item to the bottom of the shopping‑list page.”
|
|
||||||
|
|
||||||
- **`notion-move-pages`** – Move one or many pages/databases under a new parent
|
|
||||||
- **Input:** source page/database ID(s) + destination parent ID
|
|
||||||
- **Returns:** new parent relationship (page now lives under the target)
|
|
||||||
- **Prompt example:** “Move my weekly meeting‑notes page to the **‘Team Meetings’** page.”
|
|
||||||
|
|
||||||
- **`notion-duplicate-page`** – Clone a page (asynchronous – returns a job ID)
|
|
||||||
- **Input:** source page ID (optional target parent)
|
|
||||||
- **Returns:** job ID → duplicated page ID once the job finishes
|
|
||||||
- **Prompt example:** “Duplicate my project‑template page for the new Q3 initiative.”
|
|
||||||
|
|
||||||
## 📊 Database Management
|
|
||||||
|
|
||||||
- **`notion-create-database`** – Spin up a new database with a custom schema
|
|
||||||
- **Input:** parent page ID, title, property definitions (type, name, options)
|
|
||||||
- **Returns:** new database ID & URL
|
|
||||||
- **Prompt example:** “Create a database to track customer feedback with fields for **name**, **priority**, and **status**.”
|
|
||||||
|
|
||||||
- **`notion-update-database`** – Alter a database’s schema (add/rename fields) or rename the DB itself
|
|
||||||
- **Input:** database ID + schema changes (add property, rename, etc.)
|
|
||||||
- **Returns:** updated database object
|
|
||||||
- **Prompt example:** “Add a **‘Status’** field to our project database to track completion.”
|
|
||||||
|
|
||||||
## 💬 Collaboration & Workspace
|
|
||||||
|
|
||||||
- **`notion-create-comment`** – Post a comment on a page
|
|
||||||
- **Input:** page ID + comment text
|
|
||||||
- **Returns:** comment ID & timestamp
|
|
||||||
- **Prompt example:** “Leave a note on the quarterly review page about budget concerns.”
|
|
||||||
|
|
||||||
- **`notion-get-comments`** – List every comment on a page (supports pagination)
|
|
||||||
- **Input:** page ID
|
|
||||||
- **Returns:** array of comment objects
|
|
||||||
- **Prompt example:** “List all comments on the project‑requirements section.”
|
|
||||||
|
|
||||||
- **`notion-get-users`** – Fetch **all** workspace members
|
|
||||||
- **Input:** *(none)*
|
|
||||||
- **Returns:** array of user objects
|
|
||||||
- **Prompt example:** “Who are the members of this workspace?”
|
|
||||||
|
|
||||||
- **`notion-get-user`** – Get a single user’s profile (by ID or email)
|
|
||||||
- **Input:** user ID or email address
|
|
||||||
- **Returns:** user object (name, avatar, email, etc.)
|
|
||||||
- **Prompt example:** “Look up the profile of the person assigned to this task.”
|
|
||||||
|
|
||||||
- **`notion-get-teams`** – Retrieve all **teamspaces** (formerly “teams”) in the workspace
|
|
||||||
- **Input:** *(none)*
|
|
||||||
- **Returns:** array of team objects
|
|
||||||
|
|
||||||
- **`notion-get-self`** – Information about the bot itself and the workspace it’s linked to
|
|
||||||
- **Input:** *(none)*
|
|
||||||
- **Returns:** bot metadata + workspace metadata (ID, name, domain, etc.)
|
|
||||||
- **Prompt example:** “Which Notion workspace am I currently connected to?”
|
|
||||||
|
|
||||||
## Rate Limits
|
## Rate Limits
|
||||||
Standard [API request limits](https://developers.notion.com/reference/request-limits) apply to your use of Notion MCP, totaled across all tool calls.
|
Standard [API request limits](https://developers.notion.com/reference/request-limits) apply to your use of Notion MCP, totaled across all tool calls.
|
||||||
@@ -468,7 +378,9 @@ If you encounter rate limit errors, prompt your model to reduce the number of pa
|
|||||||
|
|
||||||
## Troubleshooting
|
## Troubleshooting
|
||||||
|
|
||||||
### Error: `Failed to connect to MCP server 'ntn'`
|
### Connection Errors
|
||||||
|
|
||||||
|
#### `Failed to connect to MCP server 'ntn'`
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@@ -480,27 +392,26 @@ If you encounter rate limit errors, prompt your model to reduce the number of pa
|
|||||||
4. This will trigger the redirect to Notion's authorization page to complete the "Connect with Notion MCP" authorization flow again.
|
4. This will trigger the redirect to Notion's authorization page to complete the "Connect with Notion MCP" authorization flow again.
|
||||||
5. Once authorized successfully, the connection will work across all chats again, including for models with the tool enabled by default.
|
5. Once authorized successfully, the connection will work across all chats again, including for models with the tool enabled by default.
|
||||||
|
|
||||||
### Error: `OAuth callback failed: mismatching_state`
|
#### `OAuth callback failed: mismatching_state`
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
If you receive this red error toast when registering the client or connecting via the tool toggle, it is likely due to a URL mismatch.
|
|
||||||
|
|
||||||
* **Cause:** You are likely accessing Open WebUI via `localhost` (e.g., `http://localhost:3000`), but your instance is configured with a public domain via the `WEBUI_URL` environment variable (e.g., `https://chat.mydomain.com`). The OAuth session state created on `localhost` is lost when the callback redirects to your public domain.
|
* **Cause:** You are likely accessing Open WebUI via `localhost` (e.g., `http://localhost:3000`), but your instance is configured with a public domain via the `WEBUI_URL` environment variable (e.g., `https://chat.mydomain.com`). The OAuth session state created on `localhost` is lost when the callback redirects to your public domain.
|
||||||
* **Fix:** Access your Open WebUI instance using the **exact URL** defined in `WEBUI_URL` (your public domain) and perform the setup again. **Do not use `localhost` for OAuth setups if a domain is configured.**
|
* **Fix:** Access your Open WebUI instance using the **exact URL** defined in `WEBUI_URL` (your public domain) and perform the setup again. **Do not use `localhost` for OAuth setups if a domain is configured.**
|
||||||
|
|
||||||
### Error: `Object not found`
|
### Usage Errors
|
||||||
|
|
||||||
|
#### `Object not found`
|
||||||
* **Cause:** The Integration Token is valid, but the specific page has not been shared with the integration.
|
* **Cause:** The Integration Token is valid, but the specific page has not been shared with the integration.
|
||||||
* **Fix:** In Notion, go to your Integration settings > **Access** tab and ensure the page is checked, or visit the page directly and check the **Connections** menu to ensure your integration is listed and selected.
|
* **Fix:** In Notion, go to your Integration settings > **Access** tab and ensure the page is checked, or visit the page directly and check the **Connections** menu to ensure your integration is listed and selected.
|
||||||
|
|
||||||
### Error: `Tool execution failed` (Local Method)
|
#### `Tool execution failed` (Local Method)
|
||||||
* **Cause:** Open WebUI is unable to execute the local command (npx/docker) because it is missing from the container, or the configuration is incorrect.
|
* **Cause:** Open WebUI is unable to execute the local command (npx/docker) because it is missing from the container, or the configuration is incorrect.
|
||||||
* **Fix:** Native local execution is not supported. Ensure you are using **MCPO** (Method 2) to bridge these commands, rather than entering them directly into Open WebUI's config, or switch to **Method 1 (Streamable HTTP)** in the Configuration section above. This runs on Notion's servers and requires no local dependencies.
|
* **Fix:** Native local execution is not supported. Ensure you are using **MCPO** (Method 2) to bridge these commands, rather than entering them directly into Open WebUI's config, or switch to **Method 1 (Streamable HTTP)** in the Configuration section above. This runs on Notion's servers and requires no local dependencies.
|
||||||
|
|
||||||
### Error: `missing_property` when creating a page
|
#### `missing_property` when creating a page
|
||||||
* **Cause:** The model is trying to create a page without specifying a **Parent ID**. Notion requires every page to exist inside another page or database.
|
* **Cause:** The model is trying to create a page without specifying a **Parent ID**. Notion requires every page to exist inside another page or database.
|
||||||
* **Fix:** Instruct the model in your prompt: *"Search for my 'Notes' page first, get its ID, and create the new page inside there."*
|
* **Fix:** Instruct the model in your prompt: *"Search for my 'Notes' page first, get its ID, and create the new page inside there."*
|
||||||
|
|
||||||
### Error: `RateLimitedError` (429)
|
#### `RateLimitedError` (429)
|
||||||
* **Cause:** You have exceeded Notion's API limits (approx. 3 requests/second).
|
* **Cause:** You have exceeded Notion's API limits (approx. 3 requests/second).
|
||||||
* **Fix:** Ask the model to perform actions sequentially rather than all at once (e.g., "Search for X, then wait, then search for Y").
|
* **Fix:** Ask the model to perform actions sequentially rather than all at once (e.g., "Search for X, then wait, then search for Y").
|
||||||
|
|||||||
Reference in New Issue
Block a user