Notion Worklog MCP

英文自述

概念工作日志mcp

notion-worklog-mcp是一个本地MCP服务器，可帮助您根据Git历史记录在Notion中积累工作内容文档。

此包基于两种流创建。

1. 记录正在进行的工作
2. 记录恢复过去日期或特定提交条件的任务

包本身不会生成语句。相反，提供以下内容。

• 收集Git上下文
• 提供内置模板
• 验证Notion目标
• 按日期的Notion页面append

最终Markdown由Codex、Cursor、Claude等MCP客户端编写。

此软件包所做的工作

默认行为如下：

• 根据当前Git存储库收集工作。
• 基本上 Work Documentation Calendar创建或重新使用名为的Notion数据库。
• 每天按日期使用一页。
• 将已审阅的Markdown累积到该日期页面的底部。

支持范围：

• 记录当前更改
• 基于过去的日期记录
• 记录特定提交条件

快速入门

1.安装软件包

在项目中本地安装：

npm install -D notion-worklog-mcp

在MCP设置中， npx也可以直接运行。

npx --yes notion-worklog-mcp

2.创建Notion Integration

1. https://www.notion.so/profile/integrations转到。
2. New integration单击。
3. 名称示例： Worklog MCP。
4. 至少打开以下capability。

- read_content - update_content

1. 复制Internal Integration Token。

3.准备父页面

1. 为工作文档准备一个常规Notion页面，其中包含两个数据库。
2. 打开页面右上角菜单。
3. Connections 或 Add connections单击。
4. 连接刚刚创建的integration。

此页面 NOTION_PARENT_PAGE_ID 目标。

以下两种都可以使用。

• 页面URL
• 原始页面ID

4. .env 设置

在要记录任务的存储库根目录中 .env.local创建。

NOTION_API_KEY=secret_xxx
NOTION_PARENT_PAGE_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
NOTION_DATA_SOURCE_ID=
WORKLOG_DATABASE_TITLE=Work Documentation Calendar
WORKLOG_TIME_ZONE=Asia/Seoul

必需值：

• NOTION_API_KEY
• NOTION_PARENT_PAGE_ID

选择：

• NOTION_DATA_SOURCE_ID
• WORKLOG_DATABASE_TITLE
• WORKLOG_TIME_ZONE
• WORKLOG_TEMPLATE_DIR

NOTION_DATA_SOURCE_ID如果保留为空，服务器将按照以下规则工作：

• 如果父页面下有一个同名数据库，则可重复使用
• 如果没有，则在第一次append时自动创建
• 如果有两个或更多，则返回错误以防止错误记录

5.运行doctor

如果在本地安装：

npx notion-worklog-mcp-doctor

要在不安装的情况下立即检查，请：

npx --yes --package notion-worklog-mcp notion-worklog-mcp-doctor

如果正常的话，应该可以查看下面的内容。

• 当前Git分支和merge-base
• Notion是否检测到环境变量
• 父页面是否可访问
• worklog数据库是否存在

连接MCP服务器

法典

最简单的连接方式：

codex mcp add worklog -- npx --yes notion-worklog-mcp

如果需要JSON片断 示例/codex.mcp.json请参考。

光标

examples/cursor.mcp.json使用即可。

克劳德桌面

examples/claude_desktop_config json使用即可。

记录当前任务

此模式适用于以下情况：

• 整理working tree更改
• staged整理更改
• merge-base之后的提交摘要
• 整理剩余的后续工作

推荐流程：

1. validate_notion_target
2. collect_current_work_context
3. load_worklog_template 和 mode: "current"
4. assistant草拟Markdown
5. 审查草案
6. append_worklog_entry

示例提示：

지금까지 한 작업을 문서화해줘. current 템플릿을 사용하고, 먼저 초안을 보여준 뒤 승인받고 Notion에 append해줘.

基于过去的日期记录

用于恢复和记录特定日期的任务。

推荐流程：

1. validate_notion_target 和 entryDate
2. collect_historical_work_context 和 date: "YYYY-MM-DD"
3. load_worklog_template 和 mode: "historical"
4. assistant草拟Markdown
5. 审查草案
6. append_worklog_entry 与相同 entryDate

示例提示：

2026-02-11 작업 내용을 Git 기준으로 문서화해줘. historical 템플릿을 사용하고 Remaining Work 섹션은 넣지 말아줘.

记录特定提交条件

当您希望围绕一个特定提交恢复工作时使用。

推荐流程：

1. validate_notion_target
2. collect_historical_work_context 和 commit: "abc1234"
3. load_worklog_template 和 mode: "historical"
4. assistant草拟Markdown
5. 审查草案
6. append_worklog_entry

示例提示：

커밋 92aaaf9를 historical work item으로 문서화해줘. 무엇이 바뀌었는지와 왜 그런 변경이 있었는지 중심으로 작성해줘.

内置模板

包包含两个模板。

• 模板/current.md
• 模板/historical.md

规则：

• current是 Remaining Work 包括部分
• historical银 Remaining Work 不包括节

要创建自定义模板：

WORKLOG_TEMPLATE_DIR=/absolute/or/relative/path/to/templates

此目录必须包含以下两个文件：

• current.md
• historical.md

Notion存储结构

此程序包使用以下结构：

• 页面标题： YYYY-MM-DD
• Date 属性：同一日期字符串
• 按日期第1页

append规则：

• 如果有日期页面，则在现有页面上append
• 如果没有日期页面，则创建新页面
• 如果没有数据库，则在第一个append中自动创建
• 如果有多个相同日期的页面，则阻止append

Tool说明

validate_notion_target

确认项目：

• 凭据
• 访问父页面
• 数据库/数据源分析
• 目标日期页面是否可访问

输入选择：

• entryDate

collect_current_work_context

返回项目：

• 关于分支和merge-base
• merge-base之后提交
• staged/unstaged文件
• 差异统计/摘录

collect_historical_work_context

准确地说只收一个。

• date
• commit

返回项目：

• 基准日期
• 提交相关
• 变更文件
• 差异统计
• diff摘录

load_worklog_template

输入：

• mode: "current" | "historical"

append_worklog_entry

输入：

• heading
• markdown
• 可选的 entryDate
• 可选的 previewHash

故障射击

NOTION_API_KEY or NOTION_PARENT_PAGE_ID is missing.

确认：

• 在工作目标存储库根目录中 .env.local是否有
• 密钥名称是否正确
• MCP客户端是否在所需目录中运行服务器

NOTION_DATA_SOURCE_ID points to a data source that could not be found.

确认：

• 数据库是否还存在
• 是否保留integration访问权限
• 设置的ID是否为同一父页面下的数据源

Found more than one matching worklog data source under the parent page.

解决方案：

• NOTION_DATA_SOURCE_ID显式设置

No commits were found on YYYY-MM-DD.

确认：

• 日期对不对
• 该日期是否有实际提交
• WORKLOG_TIME_ZONE是否与预期的时间段一致

previewHash does not match the current payload.

草案审阅后内容已更改。必须使用新的preview hash重试。

常见问题解答

这个套餐会写到最后的句子吗？

不。仅提供Git上下文、模板和Notion append功能。实际句子由assistant编写。

为什么用这个代替普通Notion MCP服务器？

一般Notion工具通常不会一次性提供以下内容。

• 基于Git的当前任务摘要
• 恢复基于日期/提交的历史
• 内置worklog模板
• 按日期创建页面和append规则

没有助手也能用吗？

在某种程度上是可以的。 doctor和core模块也可以在脚本中使用。但主要使用方式是MCP。

historical模式包括Remaining Work吗？

不。historic模式是为了存档而故意排除的。

可以更改数据库标题吗？

好的。 WORKLOG_DATABASE_TITLE设置即可。