notion-multi-mcp 0.2.0

MCP server for managing multiple Notion accounts simultaneously

notion-multi-mcp

English | 繁體中文

---

English

An MCP (Model Context Protocol) server that lets AI assistants operate multiple Notion accounts simultaneously. Each account gets its own prefixed toolset — no conflicts, no mix-ups.

Features

• Multi-account — connect 2, 3, or more Notion workspaces in a single MCP server
• Custom prefixes — you name each account (e.g. work, personal, team), tools are auto-generated as work_search, personal_create_page, team_query_database, etc.
• 22 tools per account — full Notion API coverage: pages, databases, blocks, comments, data sources, search
• Zero conflict — each account is fully isolated with its own API key and client instance

Quick Start

Install

pip install notion-multi-mcp

Or run directly without installing:

uvx notion-multi-mcp

Configure in Claude Code

claude mcp add notion-multi -- uvx notion-multi-mcp

Then set the environment variable in your Claude Code settings (~/.claude/settings.json):

{
  "mcpServers": {
    "notion-multi": {
      "command": "uvx",
      "args": ["notion-multi-mcp"],
      "env": {
        "NOTION_ACCOUNTS": "work:ntn_your_work_key,personal:ntn_your_personal_key"
      }
    }
  }
}

Configure in Cursor / VS Code

Add to .cursor/mcp.json or .vscode/mcp.json:

{
  "mcpServers": {
    "notion-multi": {
      "command": "uvx",
      "args": ["notion-multi-mcp"],
      "env": {
        "NOTION_ACCOUNTS": "work:ntn_your_work_key,personal:ntn_your_personal_key"
      }
    }
  }
}

Configuration

Set NOTION_ACCOUNTS with comma-separated prefix:api_key pairs:

NOTION_ACCOUNTS=work:ntn_abc123,personal:ntn_def456,team:ntn_ghi789

This example creates 3 accounts × 22 tools = 66 tools:

• work_search, work_create_page, work_query_database, ...
• personal_search, personal_create_page, personal_query_database, ...
• team_search, team_create_page, team_query_database, ...

Getting Notion API Keys

1. Go to https://www.notion.so/my-integrations
2. Click "New integration" for each workspace
3. Copy the Internal Integration Secret (starts with ntn_)
4. Important: In Notion, share the pages/databases you want to access with your integration

Available Tools (per account)

Each connected account gets all 22 tools, prefixed with the account name:

#	Tool	Description
1	{prefix}_search	Search pages and databases
2	{prefix}_query_database	Query database contents (requires data_source_id)
3	{prefix}_create_page	Create a new page
4	{prefix}_retrieve_page	Get page information
5	{prefix}_update_page	Update page properties
6	{prefix}_retrieve_page_property	Get a specific page property
7	{prefix}_move_page	Move a page to a new parent
8	{prefix}_retrieve_block	Get block information
9	{prefix}_update_block	Update a block
10	{prefix}_delete_block	Delete a block
11	{prefix}_get_block_children	List child blocks
12	{prefix}_append_block_children	Append child blocks
13	{prefix}_retrieve_database	Get database schema
14	{prefix}_create_database	Create a new database
15	{prefix}_update_database	Update database properties
16	{prefix}_query_data_source	Query a data source
17	{prefix}_retrieve_data_source	Get data source info
18	{prefix}_list_data_source_templates	List data source templates
19	{prefix}_update_data_source	Update a data source
20	{prefix}_create_comment	Create a comment
21	{prefix}_retrieve_comments	List comments
22	{prefix}_get_self	Get bot user info

Usage Examples

Once configured, you can ask your AI assistant:

• "Search for 'Q1 Report' in my work Notion" → work_search
• "Create a new page in my personal Notion" → personal_create_page
• "Copy the database schema from work to team" → work_retrieve_database + team_create_database
• "List all pages in both accounts" → work_search + personal_search in parallel

Breaking Change in v0.2.0: query_database now requires data_source_id

The upstream SDK notion-client v3.x removed databases.query(). Notion's API now uses data sources instead of databases for query operations.

Before (v0.1.x):

query_database(database_id="108640b9-...")

After (v0.2.0):

query_database(data_source_id="79e0a629-...")

How to find your data_source_id: Use {prefix}_search with filter_json: {"value": "data_source", "property": "object"} to find the data source ID that corresponds to your database.

The data_source tools (query_data_source, retrieve_data_source, list_data_source_templates, update_data_source) now also use the SDK natively instead of raw HTTP requests.

Known Issue: notion-client v3.0.0 — properties silently ignored

The upstream Python SDK notion-client v3.0.0 has a bug where databases.create() and databases.update() silently drop the properties parameter, so you cannot create databases with custom columns or update existing database schemas through the SDK.

Root cause: The pick() whitelist in api_endpoints.py does not include "properties". (GitHub Issue)

Workaround: Manually add "properties" to the pick() calls in your installed notion-client package:

# Find the file
python -c "import notion_client; print(notion_client.__file__)"
# → .../site-packages/notion_client/__init__.py
# Edit: .../site-packages/notion_client/api_endpoints.py

In api_endpoints.py, find the DatabasesEndpoint class and add "properties" to both pick() calls:

# In create() — add "properties" to the pick list:
body=pick(
    kwargs,
    "parent",
    "title",
    "description",
    "properties",        # ← add this line
    "is_inline",
    "initial_data_source",
    "icon",
    "cover",
),

# In update() — add "properties" to the pick list:
body=pick(
    kwargs,
    "parent",
    "title",
    "description",
    "properties",        # ← add this line
    "is_inline",
    "icon",
    "cover",
    "in_trash",
    "is_locked",
),

This fix will be overwritten if you upgrade notion-client. Check future releases for an official fix.

Requirements

• Python 3.10+
• Notion integration API keys (create here)

Development

git clone https://github.com/kerwin77106/Notion-Multi-MCP.git
cd notion-multi-mcp

pip install -r requirements.txt

export NOTION_ACCOUNTS="dev:ntn_your_key_here"

python notion_multi_mcp.py

License

MIT

---

繁體中文

一個 MCP (Model Context Protocol) 伺服器，讓 AI 助手能同時操作多個 Notion 帳號。每個帳號擁有獨立的前綴工具集，不會混淆、不會衝突。

功能特色

• 多帳號支援 — 可連接 2 個、3 個甚至更多 Notion 工作區
• 自訂前綴 — 自由命名帳號（如 work、personal、team），工具會自動產生為 work_search、personal_create_page、team_query_database 等
• 每帳號 22 個工具 — 完整覆蓋 Notion API：頁面、資料庫、區塊、評論、資料來源、搜尋
• 完全隔離 — 每個帳號使用獨立的 API Key 和 Client 實例

快速開始

安裝

pip install notion-multi-mcp

或直接執行（不需安裝）：

uvx notion-multi-mcp

在 Claude Code 中設定

claude mcp add notion-multi -- uvx notion-multi-mcp

然後在 Claude Code 設定檔（~/.claude/settings.json）中設定環境變數：

{
  "mcpServers": {
    "notion-multi": {
      "command": "uvx",
      "args": ["notion-multi-mcp"],
      "env": {
        "NOTION_ACCOUNTS": "work:ntn_你的工作帳號金鑰,personal:ntn_你的個人帳號金鑰"
      }
    }
  }
}

在 Cursor / VS Code 中設定

新增到 .cursor/mcp.json 或 .vscode/mcp.json：

{
  "mcpServers": {
    "notion-multi": {
      "command": "uvx",
      "args": ["notion-multi-mcp"],
      "env": {
        "NOTION_ACCOUNTS": "work:ntn_你的工作帳號金鑰,personal:ntn_你的個人帳號金鑰"
      }
    }
  }
}

設定方式

設定 NOTION_ACCOUNTS 環境變數，用逗號分隔 前綴:API金鑰 組合：

NOTION_ACCOUNTS=work:ntn_abc123,personal:ntn_def456,team:ntn_ghi789

以上範例會產生 3 個帳號 × 22 個工具 = 66 個工具：

• work_search、work_create_page、work_query_database⋯
• personal_search、personal_create_page、personal_query_database⋯
• team_search、team_create_page、team_query_database⋯

取得 Notion API Key

1. 前往 https://www.notion.so/my-integrations
2. 為每個要連接的工作區點擊 「New integration」
3. 複製 Internal Integration Secret（以 ntn_ 開頭）
4. 重要：在 Notion 中，將你要存取的頁面/資料庫分享給你建立的 Integration

可用工具（每個帳號各一套）

每個連接的帳號都會取得全部 22 個工具，工具名稱加上帳號前綴：

#	工具名稱	說明
1	{前綴}_search	搜尋頁面和資料庫
2	{前綴}_query_database	查詢資料庫內容（需傳入 data_source_id）
3	{前綴}_create_page	建立新頁面
4	{前綴}_retrieve_page	取得頁面資訊
5	{前綴}_update_page	更新頁面屬性
6	{前綴}_retrieve_page_property	取得特定頁面屬性
7	{前綴}_move_page	將頁面移動到新的父頁面
8	{前綴}_retrieve_block	取得區塊資訊
9	{前綴}_update_block	更新區塊
10	{前綴}_delete_block	刪除區塊
11	{前綴}_get_block_children	列出子區塊
12	{前綴}_append_block_children	追加子區塊
13	{前綴}_retrieve_database	取得資料庫結構
14	{前綴}_create_database	建立新資料庫
15	{前綴}_update_database	更新資料庫屬性
16	{前綴}_query_data_source	查詢資料來源
17	{前綴}_retrieve_data_source	取得資料來源資訊
18	{前綴}_list_data_source_templates	列出資料來源範本
19	{前綴}_update_data_source	更新資料來源
20	{前綴}_create_comment	建立評論
21	{前綴}_retrieve_comments	列出評論
22	{前綴}_get_self	取得 Bot 使用者資訊

使用範例

設定完成後，你可以對 AI 助手說：

• 「在我的 work Notion 搜尋『Q1 報告』」→ 呼叫 work_search
• 「在 personal Notion 建一個新頁面」→ 呼叫 personal_create_page
• 「把 work 的資料庫結構複製到 team」→ 呼叫 work_retrieve_database + team_create_database
• 「列出兩個帳號的所有頁面」→ 同時呼叫 work_search 和 personal_search

v0.2.0 破壞性變更：query_database 改為需要 data_source_id

上游 SDK notion-client v3.x 移除了 databases.query()。Notion API 現在使用 data sources 取代 databases 進行查詢操作。

變更前（v0.1.x）：

query_database(database_id="108640b9-...")

變更後（v0.2.0）：

query_database(data_source_id="79e0a629-...")

如何取得 data_source_id： 使用 {前綴}_search 並帶入 filter_json: {"value": "data_source", "property": "object"} 來查詢對應資料庫的 data source ID。

data_source 系列工具（query_data_source、retrieve_data_source、list_data_source_templates、update_data_source）現在也改用 SDK 原生方法，不再使用 raw HTTP request。

已知問題：notion-client v3.0.0 — properties 參數被靜默忽略

上游 Python SDK notion-client v3.0.0 存在一個 bug：databases.create() 和 databases.update() 會靜默丟棄 properties 參數，導致無法透過 SDK 建立帶有自訂欄位的資料庫，也無法更新資料庫結構。

根本原因： api_endpoints.py 中的 pick() 白名單沒有包含 "properties"。（GitHub Issue）

解決方法： 手動在已安裝的 notion-client 套件中加入 "properties"：

# 找到檔案位置
python -c "import notion_client; print(notion_client.__file__)"
# → .../site-packages/notion_client/__init__.py
# 編輯：.../site-packages/notion_client/api_endpoints.py

在 api_endpoints.py 中找到 DatabasesEndpoint 類別，在兩個 pick() 呼叫中加入 "properties"：

# 在 create() 中 — 加入 "properties"：
body=pick(
    kwargs,
    "parent",
    "title",
    "description",
    "properties",        # ← 加入這行
    "is_inline",
    "initial_data_source",
    "icon",
    "cover",
),

# 在 update() 中 — 加入 "properties"：
body=pick(
    kwargs,
    "parent",
    "title",
    "description",
    "properties",        # ← 加入這行
    "is_inline",
    "icon",
    "cover",
    "in_trash",
    "is_locked",
),

升級 notion-client 時此修改會被覆蓋，請留意未來版本是否已修復。

系統需求

• Python 3.10+
• Notion Integration API Key（在此建立）

開發

git clone https://github.com/kerwin77106/Notion-Multi-MCP.git
cd notion-multi-mcp

pip install -r requirements.txt

export NOTION_ACCOUNTS="dev:ntn_你的金鑰"

python notion_multi_mcp.py

授權

MIT