Notion Workflow

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

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