Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions external_plugins/notion-mcp/.zcode-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
{
"name": "notion-mcp",
"version": "0.1.0",
"description": "Notion MCP integration: pages, databases, comments, page version history and Notion chat session history via the official mcp.notion.com server, with guided first-time OAuth setup.",
"author": {
"name": "Jommmain",
"url": "https://github.com/Jommmain"
},
"keywords": [
"notion",
"mcp",
"notes",
"documents",
"databases",
"oauth"
],
"mcpServers": {
"notion": {
"type": "http",
"url": "https://mcp.notion.com/mcp"
}
},
"skills": "./skills",
"description_i18n": {
"en": "Notion MCP integration: pages, databases, comments, page version history and Notion chat session history via the official mcp.notion.com server, with guided first-time OAuth setup.",
"zh-CN": "Notion MCP 集成:通过官方 mcp.notion.com 服务器访问页面、数据库、评论、页面版本历史与 Notion 聊天会话记录,并提供首次 OAuth 授权指引。"
}
}
67 changes: 67 additions & 0 deletions external_plugins/notion-mcp/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# notion-mcp

Connect ZCode to your Notion workspace through the official **Notion MCP
server** (`https://mcp.notion.com/mcp`): read, create and update pages and
databases, work with comments and discussions, browse page version history,
and search/read Notion chat session history.

## What's included

- **MCP server declaration** for the official remote Notion MCP server. After
authorization it exposes ~70 tools, grouped as:
- Pages & documents: `notion-search`, `notion-fetch`, `notion-create-pages`,
`notion-update-page`, `notion-move-pages`, `notion-duplicate-page`
- Databases: `notion-create-database`, `notion-query-data-sources`
- Comments & discussions: `notion-get-comments`, `notion-create-comment`,
`notion-set-discussion-resolved`
- Chat session history: `notion-search-sessions`, `notion-query-sessions`,
`notion-read-session-event`, `notion-send-message-to-session`
- Page version history: `notion-get-version-changes`, `notion-view-version`,
`notion-restore-version`
- Calendar & meetings, files & attachments
- **Setup skill** that guides first-time OAuth authorization and 401
troubleshooting.

## First-time setup (one time)

The Notion MCP server only whitelists a fixed list of OAuth client names, and
ZCode is not on it, so the out-of-the-box flow fails at client registration.
Authorize once with the helper script:

```bash
git clone https://github.com/Jommmain/zcode-notion-mcp
cd zcode-notion-mcp && npm install
node notion-mcp-auth.mjs
```

The script opens a browser: log in to Notion, pick the pages to share, click
Allow. It injects the tokens into ZCode's encrypted credential store
(`~/.zcode/v2/credentials.json`, backup is written alongside). Restart ZCode
(or reconnect the `notion` server) afterwards.

When access tokens expire (ZCode starts receiving 401s), re-run the script.

## Dependencies, network access and side effects

- Network: connections to `https://mcp.notion.com` (MCP + OAuth), initiated
by ZCode after installation. The helper script additionally runs a local
callback server on `localhost:3000` during authorization.
- Service dependency: a Notion account with pages the user shares with the
connection. The connection only sees pages explicitly shared during
authorization.
- File writes: none by the plugin itself. The optional helper script writes
only to `~/.zcode/v2/credentials.json` (plus a `.backup` copy).
- Command execution: the setup skill instructs running the helper script from
https://github.com/Jommmain/zcode-notion-mcp when authorization is needed.

## Third-party code and services

- **Notion MCP server** — remote service operated by Notion Labs; subject to
Notion's terms of service.
- **zcode-notion-mcp helper** (optional, MIT) —
https://github.com/Jommmain/zcode-notion-mcp — MIT-licensed, depends on the
`@modelcontextprotocol/sdk` (MIT) for the OAuth flow.

## Category

`productivity`
59 changes: 59 additions & 0 deletions external_plugins/notion-mcp/README_CN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# notion-mcp

通过 Notion **官方 MCP 服务器**(`https://mcp.notion.com/mcp`)将 ZCode 接入
Notion 工作区:读取、创建和更新页面与数据库,处理评论与讨论,查看页面版本
历史,以及搜索/读取 Notion 聊天会话记录。

## 包含内容

- **MCP 服务器声明**:官方远程 Notion MCP 服务器。授权后提供约 70 个工具:
- 页面与文档:`notion-search`、`notion-fetch`、`notion-create-pages`、
`notion-update-page`、`notion-move-pages`、`notion-duplicate-page`
- 数据库:`notion-create-database`、`notion-query-data-sources`
- 评论与讨论:`notion-get-comments`、`notion-create-comment`、
`notion-set-discussion-resolved`
- 聊天会话记录:`notion-search-sessions`、`notion-query-sessions`、
`notion-read-session-event`、`notion-send-message-to-session`
- 页面版本历史:`notion-get-version-changes`、`notion-view-version`、
`notion-restore-version`
- 日历与会议记录、文件与附件
- **配置技能**:指引首次 OAuth 授权与 401 排障。

## 首次配置(一次性)

Notion MCP 服务器只允许固定名单内的 OAuth 客户端名称,ZCode 不在其中,
开箱即用的连接会在客户端注册一步失败。请先运行辅助脚本完成授权:

```bash
git clone https://github.com/Jommmain/zcode-notion-mcp
cd zcode-notion-mcp && npm install
node notion-mcp-auth.mjs
```

脚本会打开浏览器:登录 Notion、选择要共享的页面并点击允许。随后脚本将令牌
写入 ZCode 的加密凭据库(`~/.zcode/v2/credentials.json`,同时生成 `.backup`
备份)。完成后重启 ZCode(或重连 `notion` 服务器)。

访问令牌过期(ZCode 收到 401)时,重新运行该脚本即可。

## 依赖、网络访问与副作用

- 网络:安装后由 ZCode 连接 `https://mcp.notion.com`(MCP 与 OAuth)。辅助
脚本在授权期间额外在本机 `localhost:3000` 运行回调服务器。
- 服务依赖:需要 Notion 账号;连接只能访问用户在授权时明确共享的页面。
- 文件写入:插件本身不写文件。可选的辅助脚本仅写入
`~/.zcode/v2/credentials.json`(并生成 `.backup` 备份)。
- 命令执行:配置技能在需要授权时指示运行来自
https://github.com/Jommmain/zcode-notion-mcp 的辅助脚本。

## 第三方代码与服务

- **Notion MCP 服务器** — Notion Labs 运营的远程服务,受 Notion 服务条款
约束。
- **zcode-notion-mcp 辅助脚本**(可选,MIT 许可证)—
https://github.com/Jommmain/zcode-notion-mcp ,OAuth 流程依赖
`@modelcontextprotocol/sdk`(MIT)。

## 分类

`productivity`
49 changes: 49 additions & 0 deletions external_plugins/notion-mcp/skills/notion-mcp/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
name: notion-mcp
description: Use when the user asks to read, create or update Notion pages and databases, work with page comments and discussions, browse page version history, or search/read Notion chat session history. Also covers first-time OAuth setup and 401 troubleshooting for the Notion MCP server.
---

# Notion MCP

The `notion` MCP server (official `https://mcp.notion.com/mcp`) exposes ~70 tools:
pages and databases (`notion-search`, `notion-fetch`, `notion-create-pages`,
`notion-update-page`, `notion-move-pages`, `notion-query-data-sources`), comments
and discussions (`notion-get-comments`, `notion-create-comment`,
`notion-set-discussion-resolved`), page version history
(`notion-get-version-changes`, `notion-view-version`, `notion-restore-version`),
chat sessions (`notion-search-sessions`, `notion-query-sessions`,
`notion-read-session-event`, `notion-send-message-to-session`), calendar and
meeting notes, and file uploads/downloads.

## First-time setup (OAuth)

The Notion MCP server only whitelists a fixed list of OAuth client names, and
ZCode is not on it — a plain connect fails at client registration. The
one-time workaround is an authorization helper script:

```bash
git clone https://github.com/Jommmain/zcode-notion-mcp
cd zcode-notion-mcp && npm install
node notion-mcp-auth.mjs
```

The script opens a browser: the user logs in to Notion, selects the pages to
share, and clicks Allow. It then injects the tokens into ZCode's encrypted
credential store. Afterwards restart ZCode (or reconnect the `notion` server).
Full details: https://github.com/Jommmain/zcode-notion-mcp

## Troubleshooting

- **401 from `notion` tools**: the access token expired. Re-run
`node notion-mcp-auth.mjs` from the helper repository, then restart ZCode.
- **A page is not found / not visible**: the connection only sees pages the
user shared during authorization. Tell the user to open the page in Notion →
`···` → Connections → grant access, then retry.

## Working rules

- Prefer `notion-search` first; never invent page or database ids.
- Chat session history: `notion-search-sessions` / `notion-query-sessions`,
then `notion-read-session-event` for details.
- Deleting pages (`notion-delete-pages`) moves them to trash — confirm with
the user before destructive calls.
72 changes: 59 additions & 13 deletions marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,10 @@
"url": "https://z.ai"
},
"unlistedPlugins": [
{ "name": "openpencil", "source": "./external_plugins/openpencil" }
{
"name": "openpencil",
"source": "./external_plugins/openpencil"
}
],
"plugins": [
{
Expand Down Expand Up @@ -827,7 +830,9 @@
},
{
"name": "excalidraw",
"componentTypes": ["ui"],
"componentTypes": [
"ui"
],
"displayName": "Excalidraw",
"displayName_i18n": {
"en": "Excalidraw",
Expand All @@ -850,7 +855,9 @@
"name": "photocraft",
"icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/photocraft/icon.png",
"source": "./external_plugins/photocraft",
"componentTypes": ["ui"],
"componentTypes": [
"ui"
],
"displayName": "PhotoCraft",
"displayName_i18n": {
"en": "PhotoCraft",
Expand All @@ -877,7 +884,9 @@
"name": "vectorcraft",
"icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/vectorcraft/icon.png",
"source": "./external_plugins/vectorcraft",
"componentTypes": ["ui"],
"componentTypes": [
"ui"
],
"displayName": "VectorCraft",
"displayName_i18n": {
"en": "VectorCraft",
Expand All @@ -904,7 +913,9 @@
"name": "pdfcraft",
"icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/pdfcraft/icon.png",
"source": "./external_plugins/pdfcraft",
"componentTypes": ["ui"],
"componentTypes": [
"ui"
],
"displayName": "PdfCraft",
"displayName_i18n": {
"en": "PdfCraft",
Expand All @@ -931,7 +942,9 @@
"name": "designcraft",
"icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/designcraft/icon.png",
"source": "./external_plugins/designcraft",
"componentTypes": ["ui"],
"componentTypes": [
"ui"
],
"displayName": "DesignCraft",
"displayName_i18n": {
"en": "DesignCraft",
Expand All @@ -958,7 +971,9 @@
"name": "wordcraft",
"icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/wordcraft/icon.png",
"source": "./external_plugins/wordcraft",
"componentTypes": ["ui"],
"componentTypes": [
"ui"
],
"displayName": "WordCraft",
"displayName_i18n": {
"en": "WordCraft",
Expand All @@ -985,7 +1000,9 @@
"name": "gridcraft",
"icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/gridcraft/icon.png",
"source": "./external_plugins/gridcraft",
"componentTypes": ["ui"],
"componentTypes": [
"ui"
],
"displayName": "GridCraft",
"displayName_i18n": {
"en": "GridCraft",
Expand All @@ -1012,7 +1029,9 @@
"name": "deckcraft",
"icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/deckcraft/icon.png",
"source": "./external_plugins/deckcraft",
"componentTypes": ["ui"],
"componentTypes": [
"ui"
],
"displayName": "DeckCraft",
"displayName_i18n": {
"en": "DeckCraft",
Expand All @@ -1039,7 +1058,9 @@
"name": "cadcraft",
"icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/cadcraft/icon.png",
"source": "./external_plugins/cadcraft",
"componentTypes": ["ui"],
"componentTypes": [
"ui"
],
"displayName": "CADCraft",
"displayName_i18n": {
"en": "CADCraft",
Expand All @@ -1066,7 +1087,9 @@
"name": "soundcraft",
"icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/soundcraft/icon.png",
"source": "./external_plugins/soundcraft",
"componentTypes": ["ui"],
"componentTypes": [
"ui"
],
"displayName": "SoundCraft",
"displayName_i18n": {
"en": "SoundCraft",
Expand Down Expand Up @@ -1149,7 +1172,9 @@
},
"category": "developer-tools",
"icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/kicad/icon.png",
"componentTypes": ["ui"],
"componentTypes": [
"ui"
],
"displayName": "KiCad",
"displayName_i18n": {
"en": "KiCad",
Expand Down Expand Up @@ -1443,6 +1468,27 @@
"mcp",
"verification"
]
},
{
"name": "notion-mcp",
"source": "./external_plugins/notion-mcp",
"description": "Notion MCP integration: pages, databases, comments, page version history and Notion chat session history via the official mcp.notion.com server, with guided first-time OAuth setup.",
"description_i18n": {
"en": "Notion MCP integration: pages, databases, comments, page version history and Notion chat session history via the official mcp.notion.com server, with guided first-time OAuth setup.",
"zh-CN": "Notion MCP 集成:通过官方 mcp.notion.com 服务器访问页面、数据库、评论、页面版本历史与 Notion 聊天会话记录,并提供首次 OAuth 授权指引。"
},
"version": "0.1.0",
"author": {
"name": "Jommmain"
},
"category": "productivity",
"keywords": [
"notion",
"mcp",
"notes",
"documents",
"oauth"
]
}
]
}
}