---
title: Notion (MCP)
sidebar_label: Notion MCP Integration
sidebar_position: 50
description: Connect Open WebUI to your Notion workspace using the Model Context Protocol (MCP) to search, read, and create pages with automatic Markdown conversion. Supports native Streamable HTTP or self-hosted setups via MCPO.
keywords: [notion, mcp, model context protocol, integration, productivity, tools, markdown, npx, docker, mcpo, local cli, streamable http, oauth]
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
This guide enables Open WebUI to interact with your Notion workspace—searching pages, reading content, creating docs, and managing databases—using the **Model Context Protocol (MCP)**.
:::info Why this Integration?
This integration utilizes the official Notion MCP server, which specializes in **automatic Markdown conversion**. When the AI reads a Notion page, it receives clean, structured Markdown rather than raw JSON blocks, significantly improving the model's ability to understand and summarize your notes.
:::
:::warning Community Contribution
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/).
:::
## Method 1: Streamable HTTP (Recommended)
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.
:::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**.
2. Click the **+** (Plus) button to add a new tool.
3. Click **Import** (top right of the modal).
4. Paste the following JSON snippet:
```json title="Notion Remote MCP Configuration"
[
{
"type": "mcp",
"url": "https://mcp.notion.com/mcp",
"spec_type": "url",
"spec": "",
"path": "openapi.json",
"auth_type": "oauth_2.1",
"key": "",
"info": {
"id": "ntn",
"name": "Notion",
"description": "A note-taking and collaboration platform that allows users to create, organize, and share notes, databases, and other content."
}
}
]
```
5. **Register:** Click the **Register Client** button (next to the Auth dropdown).
6. Click **Save**.
### 2. Authenticate & Grant Access
Once the tool is added, you must authenticate to link your specific workspace.
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**.
5. **Authorize:** You will be redirected to a "Connect with Notion MCP" screen.
* Ensure the correct **Workspace** 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 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.
This configuration uses the official Node.js package.
```json title="mcpo-config.json"
{
"mcpServers": {
"notion": {
"command": "npx",
"args": [
"-y",
"@notionhq/notion-mcp-server"
],
"env": {
"NOTION_TOKEN": "secret_YOUR_KEY_HERE"
}
}
}
}
```
This configuration uses the official Docker image.
```json title="mcpo-config.json"
{
"mcpServers": {
"notion": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"NOTION_TOKEN",
"mcp/notion"
],
"env": {
"NOTION_TOKEN": "secret_YOUR_KEY_HERE"
}
}
}
}
```
### 2. Connect Open WebUI
Once MCPO is running and configured with Notion:
1. Navigate to **Admin Panel > Settings > External Tools**.
2. Click the **+** (Plus) button.
3. Click **Import** (top right of the modal).
4. Paste the following JSON snippet (update the URL with your MCPO address):
```json title="MCPO Connection JSON"
[
{
"type": "openapi",
"url": "http://:/notion",
"spec_type": "url",
"spec": "",
"path": "openapi.json",
"auth_type": "bearer",
"key": "",
"info": {
"id": "notion-local",
"name": "Notion (Local)",
"description": "Local Notion integration via MCPO"
}
}
]
```
5. Click **Save**.
---
## Creating an Internal Integration
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.
:::
### 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**.
**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 (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.
3. Scroll down to the **Tools** section.
4. Check the box for **Notion**.
5. Click **Save & Update**.
## Building a Specialized Notion Agent (Optional)
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.
### Step 1: Create a Knowledge Base for the Agent
First, create a knowledge base with the official Notion MCP documentation. This will help the model understand its own capabilities.
1. **Navigate to Knowledge:** Go to **Workspace > Knowledge**.
2. **Create New Knowledge Base:** Click the **+ New Knowledge** button.
3. **Fill in Details:**
* **Name:** `Notion MCP Docs`
* **Description:** `Official documentation for Notion's MCP tools to improve agent accuracy.`
4. Click **Create Knowledge**.
5. **Upload Content:**
* Save the content from the [Notion MCP Documentation](https://developers.notion.com/docs/mcp-supported-tools) as a PDF or `.txt` file.
* Inside your new knowledge base, click the **+ Add Content** button and upload the file you saved.
:::tip Recommended: Optimize with Jina Reader
For optimal RAG performance, we recommend converting web documentation into clean Markdown. You can use **[Jina Reader](https://github.com/jina-ai/reader)** (or the hosted `https://r.jina.ai/` API) to strip clutter and format the page specifically for LLMs.
Simply visit `https://r.jina.ai/https://developers.notion.com/docs/mcp-supported-tools`, copy the output, and save it as a `.md` file to upload.
:::
### Step 2: Create the Custom Model
Now, create the dedicated agent and attach the knowledge base you just made.
1. Go to **Workspace > Models > Create a Model**.
2. **Name:** `Notion Assistant`
3. **Description:** `An intelligent agent that manages your Notion workspace using MCP tools to search, read, and create content.`
4. **Base Model:** Select your preferred local LLM (e.g., Llama 3.1).
5. **Tools:** Enable **Notion**.
6. **System Prompt:** Paste the following optimized prompt:
Click to view Optimized System Prompt
```markdown
You are the Notion Workspace Manager, an intelligent agent connected directly to the user's Notion workspace via the Model Context Protocol (MCP). Your goal is to help the user organize, retrieve, and generate content within their personal knowledge base.
### CRITICAL OPERATIONAL RULES:
1. **SEARCH IS MANDATORY:**
- You cannot interact with a page or database without its unique ID or URL.
- If the user refers to a page by name (e.g., "Add this to my Todo list"), you MUST first run `notion-search` to find the correct page and retrieve its ID or URL.
- NEVER guess a Page ID.
- If a search returns multiple results (e.g., two pages named "Meeting Notes"), ask the user to clarify which one to use before proceeding.
2. **READ BEFORE ANSWERING:**
- If the user asks a question about their data (e.g., "What is the status of Project Alpha?"), do not answer from your internal training data.
- First `notion_search` for the relevant page, then `notion-read-page` to get the content, and finally answer based *strictly* on the tool output.
- Note: Page content is returned to you as Markdown. Preserve this structure in your response.
3. **CREATION PROTOCOLS:**
- When asked to create a page (`notion-create-page`), you must identify a Parent Page ID.
- If the user does not specify a location, search for a logical parent page (like "Dashboard", "Projects", or "Notes") or ask the user where to put it.
4. **CONTENT FORMATTING:**
- When appending content (`notion-append-block`) or creating pages, use clean Markdown.
- Structure complex information with headers, bullet points, and checkboxes to utilize Notion's block structure effectively.
### ERROR HANDLING:
- If a tool returns "Object not found" or an empty search result, inform the user: "I cannot see that page. Please ensure you have connected it to the Open WebUI integration via the '...' menu > Connections in Notion."
### BEHAVIORAL PERSONA:
- Be concise and action-oriented.
- Confirm actions after completion (e.g., "✅ I have added that task to your 'Tasks' database.").
- If you are analyzing a large amount of text from a Notion page, provide a structured summary unless asked for specific details.
```
7. **Attach Knowledge Base:**
* 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.
:::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).
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:**
Under the **Prompts** section, click the **+** button to add a few helpful starting prompts.
| # | Title | Subtitle | Prompt |
|---|----------------------|--------------------------|-----------------------------------------------------------------------------------------------------------|
| 1 | Search my workspace | for a specific page | Search Notion for my **'Project Roadmap'** page. |
| 2 | Summarize a page | after finding it first | First, search for the **'Onboarding Guide'** page, then read its content and give me a summary. |
| 3 | Add a new task | to my main to‑do list | Find my **'To‑Do List'** page and add a new task: **“Follow up with the design team.”** |
9. Finally, **Save & Update** the model.
## Supported Tools
:::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.
:::
This integration supports a wide range of tools for searching, reading, creating, and updating Notion pages and databases.
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)**.
## 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.
- **General Limit:** Average of **180 requests per minute** (3 requests per second).
- **Search-Specific Limit:** **30 requests per minute**.
:::warning Rate Limits
If you encounter rate limit errors, prompt your model to reduce the number of parallel searches or operations. For example, instead of "Search for A, B, and C," try asking for them sequentially.
:::
## Troubleshooting
### Connection Errors
#### `Failed to connect to MCP server 'ntn'`
* **Cause:** This usually indicates that your OAuth session with Notion has expired or the token needs a refresh. This often occurs after restarting Open WebUI or after a period of inactivity.
* **Fix:**
1. Open any chat.
2. Click the **+** (Plus) button > **Integrations > Tools**.
3. Toggle the **Notion** switch **ON**.
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.
#### `OAuth callback failed: mismatching_state`
* **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.**
### Usage Errors
#### `Object not found`
* **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.
#### `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.
* **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.
#### `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.
* **Fix:** Instruct the model in your prompt: *"Search for my 'Notes' page first, get its ID, and create the new page inside there."*
#### `RateLimitedError` (429)
* **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").