Skip to main content
Glama

notion-workflow-mcp

Personal workflow management via Claude CLI + Notion API, built as an MCP Server.

Features

  • 19 MCP tools — task lifecycle, subtask management, note-taking, aggregations

  • 12 skills — slash commands + natural language triggers, globally installable

  • 2 Notion databases — 工作流库 (tasks) + 笔记库 (notes), independent

  • Project-based task management — tasks belong to projects, with embedded subtasks (priority + status)

  • Conversation-to-note — /note auto-summarizes AI conversations into structured notes

  • Ebbinghaus review — /recall schedules spaced repetition based on note creation dates

Related MCP server: Taskflow MCP

Requirements

  • Python 3.11+

  • uv (recommended) or pip

  • Notion account + Integration token

Setup

1. Clone & install

git clone <repo-url>
cd notion-workflow-mcp
uv venv --python python3.12
uv pip install -e .

2. Configure environment

cp .env.example .env
# Fill in: NOTION_TOKEN, WORKFLOW_DATABASE_ID, NOTES_DATABASE_ID
  • NOTION_TOKEN: notion.so/my-integrations → New integration → copy token

  • Database IDs: Open database in Notion → URL 中 notion.so/<database_id>?v=...

3. Share databases with Integration

In Notion: open each database → ... → Connections → select your integration.

4. Initialize database schema

python scripts/init_databases.py

Auto-adds required properties (状态, 优先级, 项目, 截止日期, 标签, 备注) to existing databases.

5. Register MCP Server

claude mcp add notion-workflow -- /path/to/.venv/bin/python /path/to/server.py

Or add to ~/.claude/settings.json:

{
  "mcpServers": {
    "notion-workflow": {
      "command": "/path/to/notion-workflow-mcp/.venv/bin/python",
      "args": ["/path/to/notion-workflow-mcp/server.py"]
    }
  }
}

6. Install skills

Skills defined in .claude/skills/ provide slash commands and natural language triggers. In-repo they're auto-discovered; to use from any directory, run:

bash scripts/install-skills.sh

This copies all skills to ~/.claude-internal/skills/. Restart Claude Code session to take effect.

Workflow

# Create a task
/capture 重构Notion MCP -p MCP改造 -d 2026-03-28

# Add subtasks
/subtask abc123 去掉关联功能 -pri 高
/subtask abc123 增加项目字段

# View tasks
/task_list

# Start working
/status abc123 doing 去掉关联功能

# Save conversation knowledge
/note

# Mark done
/status abc123 done 去掉关联功能

# Update progress
/progress abc123

# Daily standup
/standup

# Weekly review
/review this week

# Ebbinghaus review
/recall

Skills

Skill

Trigger

Description

capture

/capture, "创建任务"

Quick-create a task

subtask-add

/subtask, "添加子目标"

Add subtask to a task

task-list

/task_list, "任务列表"

View incomplete tasks by project

status

/status, "标记完成"

Change task/subtask status (atomic)

detail

/detail, "写进展"

Update subtask detail

progress

/progress, "汇总进展"

Summarize & save progress

note

/note, "记笔记"

Summarize conversation to note

find

/find, "搜索"

Search tasks and notes

standup

/standup, "站会"

Daily standup report

review

/review, "复盘"

Date-range review report

recall

/recall, "复习"

Ebbinghaus spaced repetition

decompose-task

/decompose, "拆解任务"

Extract task + subtasks from conversation

MCP Tools

Group

Tools

Workflow

list_tasks get_task create_task update_task append_task search_tasks

Subtasks

get_subtasks update_subtasks update_subtask_detail update_subtask_status

Notes

list_notes get_note create_note append_note search_notes

Aggregations

get_overview get_today_tasks generate_standup generate_review

Database Schema

工作流库 (Tasks) 名称 · 状态 · 优先级 · 项目 · 截止日期 · 标签 · 备注

Subtasks are embedded in task page body as a table:

子目标

优先级

状态

功能A

🟡 高

⬜ 待办

功能B

🟢 普通

🔄 进行中

功能C

🔴 紧急

✅ 完成

Each subtask can have a detail section (heading_3 + paragraphs) below the table.

笔记库 (Notes) 名称 · 类型 (会议记录/想法/参考/速记) · 标签

Project Structure

├── server.py              # FastMCP server entry
├── notion/
│   ├── client.py          # Notion API client
│   └── models.py          # Pydantic models & enums
├── tools/
│   ├── workflow.py        # Task management tools
│   ├── notes.py           # Note tools
│   └── aggregations.py    # Standup, review, overview
├── .claude/skills/        # 12 skills (source of truth)
└── scripts/
    ├── init_databases.py  # Database schema setup
    └── install-skills.sh  # Install skills globally

Available Tools

19 tools
append_noteA

向已有笔记追加内容(追加到页面 body 末尾)。

Args: note_id: 笔记 ID content: 要追加的文本内容

Returns: 更新后的笔记元信息(不含完整 body)

Inputs: note_id (required), content (required). Returns: object

append_taskA

向已有任务追加内容(追加到页面 body 末尾)。

Args: task_id: 任务的 Notion 页面 ID content: 要追加的文本内容

Returns: 更新后的任务元信息(不含完整 body)

Inputs: task_id (required), content (required). Returns: object

complete_taskB

将任务标记为"完成",并在页面 body 中记录完成时间和可选总结。

Args: task_id: 要完成的任务 ID summary: 可选的完成总结/备注,会追加到页面 body

Returns: 更新后的任务详情

Inputs: task_id (required), summary. Returns: object

create_noteB

在笔记库中创建一篇新笔记。

Args: title: 笔记标题(必填) content: 笔记正文(必填,支持纯文本/Markdown) note_type: 笔记类型,可选:会议记录 | 想法 | 参考 | 速记,默认速记 tags: 标签列表,如 ["前端", "架构"],可选

Returns: 创建成功的笔记详情

Inputs: title (required), content (required), note_type, tags. Returns: object

create_taskA

在工作流库中创建一个新任务(状态默认为"待办")。

Args: name: 任务名称(必填) project: 所属项目名称,可选 priority: 优先级,可选:🔴 紧急 | 🟡 高 | 🟢 普通,默认 🟢 普通 due_date: 截止日期,格式 YYYY-MM-DD,可选 tags: 标签列表,如 ["开发", "前端"],可选 note: 备注说明,可选

Returns: 创建成功的任务详情

Inputs: name (required), project, priority, due_date, +2 more. Returns: object

generate_standupB

自动生成每日站会内容:昨日完成 / 今日计划 / 阻塞项。

Returns: StandupReport 字典,包含三个列表和生成时间

Inputs: no named parameters. Returns: object

generate_weekly_reviewB

生成工作周报/复盘,默认为本周,week_offset=-1 为上周。

Args: week_offset: 0 = 本周,-1 = 上周,以此类推

Returns: WeeklyReview 字典,包含完成任务、进行中任务、创建笔记数和总结

Inputs: week_offset. Returns: object

get_noteA

获取单篇笔记的完整详情(含 body 内容)。

Args: note_id: Notion 页面 ID include_content: 是否返回页面 body 内容,默认 True

Returns: 笔记详情,如果 include_content=True 则包含 content 字段

Inputs: note_id (required), include_content. Returns: object

get_overviewB

获取工作流库的任务状态概览(各状态数量仪表盘)。

Returns: 包含 todo / in_progress / done / on_hold / total 数量的字典

Inputs: no named parameters. Returns: object

get_subtasksB

获取任务的子目标列表(解析任务页面 body 中的子目标 Markdown)。

Args: task_id: 任务的 Notion 页面 ID

Returns: 子目标列表 [{name, status, priority}],status: todo | doing | done

Inputs: task_id (required). Returns: result

get_taskB

获取单个任务的完整详情。

Args: task_id: Notion 页面 ID(可从 list_tasks 结果中获取)

Returns: 任务详情(字典格式)

Inputs: task_id (required). Returns: object

get_today_tasksA

获取今日相关任务:今天到期的任务 + 所有进行中的任务。

Returns: 任务列表,按优先级排序

Inputs: no named parameters. Returns: result

list_notesB

列出笔记库中的笔记。

Args: note_type: 按类型过滤,可选:会议记录 | 想法 | 参考 | 速记 tag: 按标签过滤,精确匹配单个标签名称 limit: 返回条数,默认 20,最大 100

Returns: 笔记列表(字典格式,不含 body 内容)

Inputs: note_type, tag, limit. Returns: result

list_tasksB

列出工作流库中的任务。

Args: status: 按状态过滤,可选值:待办 | 进行中 | 完成 | 搁置 priority: 按优先级过滤,可选值:🔴 紧急 | 🟡 高 | 🟢 普通 tag: 按标签过滤,精确匹配单个标签名称 limit: 返回条数,默认 20,最大 100 project: 按项目过滤,精确匹配项目名称

Returns: 任务列表(字典格式)

Inputs: status, priority, tag, limit, +1 more. Returns: result

search_notesC

在笔记库中全文搜索笔记。

Args: query: 搜索关键词

Returns: 匹配的笔记列表

Inputs: query (required). Returns: result

search_tasksC

在工作流库中全文搜索任务。

Args: query: 搜索关键词

Returns: 匹配的任务列表

Inputs: query (required). Returns: result

start_taskA

将任务从"待办"推进到"进行中",并在页面 body 中记录开始时间。

Args: task_id: 要开始的任务 ID

Returns: 更新后的任务详情

Inputs: task_id (required). Returns: object

update_subtasksA

更新任务的子目标列表(重写页面 body 中的子目标区块)。

Args: task_id: 任务的 Notion 页面 ID subtasks: 完整子目标列表 [{name: str, status: str, priority: str}] status: todo | doing | done priority: 🔴 紧急 | 🟡 高 | 🟢 普通

Returns: 更新后的子目标列表

Inputs: task_id (required), subtasks (required). Returns: result

update_taskA

更新一个已有任务的属性(只传需要修改的字段)。

Args: task_id: Notion 页面 ID(必填) status: 新状态,可选:待办 | 进行中 | 完成 | 搁置 priority: 新优先级,可选:🔴 紧急 | 🟡 高 | 🟢 普通 due_date: 新截止日期,格式 YYYY-MM-DD tags: 新标签列表(会完整替换原有标签) note: 新备注(会替换原有备注) project: 所属项目名称

Returns: 更新后的任务详情

Inputs: task_id (required), status, priority, due_date, +3 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 19 tools

    Disambiguation4/5

    Most tools have distinct purposes clearly separated between notes and tasks, with clear action boundaries (e.g., create_note vs. create_task, get_note vs. get_task). However, append_note and append_task are functionally similar (both append content to pages) and could potentially be confused if an agent doesn't carefully check the resource type, creating minor ambiguity.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern throughout (e.g., create_note, get_task, update_subtasks, list_notes). All names use snake_case consistently, and verbs are appropriately chosen for the actions (create, get, list, update, append, complete, start, generate, search). There are no deviations in naming conventions.

    Tool Count4/5

    19 tools is slightly high but reasonable for a workflow management system covering notes, tasks, subtasks, and reporting. The count supports comprehensive operations without being overwhelming, though it borders on the upper limit of typical well-scoped servers (15-20 tools).

    Completeness5/5

    The toolset provides complete CRUD/lifecycle coverage for both notes and tasks, including creation, retrieval, updating, listing, searching, and status transitions (e.g., start_task, complete_task). It also includes advanced features like subtask management, overview dashboards, and automated reporting (standup, weekly review), leaving no obvious gaps for the Notion workflow domain.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Persistent, cross-session task management for Claude Code. 24 MCP tools for tasks, projects, dependencies, and docs. 7 skills for planning, standups, and handoffs. Event-sourced storage with per-project isolation.
      5
      MIT