mirror of
https://github.com/open-webui/docs.git
synced 2025-12-12 07:29:49 +07:00
docs: Notion MCP refactor
This commit is contained in:
silentoplayz
@@ -19,91 +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/).
|
||||
:::
|
||||
|
||||
## Prerequisites
|
||||
## Method 1: Streamable HTTP (Recommended)
|
||||
|
||||
:::info Note for Streamable HTTP
|
||||
If you plan to use **Method 1 (Streamable HTTP)**, the OAuth flow may handle the integration creation automatically. However, we highly recommend following the steps below regardless. This ensures you have granular control over page permissions and a valid **Internal Integration Secret** available for troubleshooting or manual configuration.
|
||||
:::
|
||||
|
||||
Regardless of the connection method chosen, you should create an internal integration within Notion to ensure you have the necessary credentials and permission scopes.
|
||||
|
||||
### 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**.
|
||||
|
||||
**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.
|
||||
:::
|
||||
|
||||
:::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.
|
||||
|
||||
### 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.
|
||||
|
||||
1. Navigate to **Admin Panel > Settings > External Tools**.
|
||||
@@ -130,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.
|
||||
6. **Register:** Click the **Register Client** button (next to the Auth dropdown).
|
||||
7. Click **Save**.
|
||||
5. **Register:** Click the **Register Client** button (next to the Auth dropdown).
|
||||
6. 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)">
|
||||
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**.
|
||||
1. Open any chat window.
|
||||
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
|
||||
Follow the installation instructions in the [MCPO Repository](https://github.com/open-webui/mcpo) to get it running (usually done via Docker).
|
||||
5. **Authorize:** You will be redirected to a "Connect with Notion MCP" screen.
|
||||
* Ensure the correct **Workspace** is selected in the dropdown.
|
||||
* Click **Continue**.
|
||||
|
||||
### Step 2: Configure MCPO
|
||||
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.
|
||||
:::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, 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>
|
||||
<TabItem value="npx" label="Node (npx)" default>
|
||||
@@ -171,7 +120,7 @@ To run the server locally (using Docker or Node.js), you must use the **MCPO Bri
|
||||
```
|
||||
</TabItem>
|
||||
<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"
|
||||
{
|
||||
@@ -196,7 +145,7 @@ To run the server locally (using Docker or Node.js), you must use the **MCPO Bri
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Step 3: Connect Open WebUI
|
||||
### 2. Connect Open WebUI
|
||||
Once MCPO is running and configured with Notion:
|
||||
|
||||
1. Navigate to **Admin Panel > Settings > External Tools**.
|
||||
@@ -223,40 +172,82 @@ To run the server locally (using Docker or Node.js), you must use the **MCPO Bri
|
||||
]
|
||||
```
|
||||
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
|
||||
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.
|
||||
Required for **Method 2**, creating an internal integration within Notion ensures you have the necessary credentials and permission scopes readily available.
|
||||
|
||||
### 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. Click the **+** (Plus) button in the chat input bar.
|
||||
3. Navigate to **Integrations > Tools**.
|
||||
4. Toggle the **Notion** switch to **ON**.
|
||||
### 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 MCPO configuration.
|
||||
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.
|
||||
* 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, revisit steps 1-4 of this option to complete the "Connect with Notion MCP" authorization flow again.
|
||||
**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.
|
||||
:::
|
||||
|
||||
|
||||
:::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**.
|
||||
2. Click the **pencil icon** to edit a model.
|
||||
|
||||
Reference in New Issue
Block a user