This is a submission for the Notion MCP Challenge.
What I Built
Ever wished your Notion workspace could come alive every morning with fresh, personalized content? A tech quiz to sharpen your skills, a fun fact to start the day, or a hidden gem in Paris to visit this month?
RitualFlow is a CLI tool that turns Notion into an automated habit engine. You define habits in a Notion database — each with a frequency (daily, weekly, monthly) and an AI prompt — and RitualFlow generates rich, personalized content pages automatically using Claude.
Think of it as a personal content assistant that reads your Notion config, generates AI content with web search capabilities, and writes beautifully formatted pages back into Notion — with deduplication, progress tracking, and a live dashboard.
What it actually does
- Reads your habit definitions from a Notion database (name, frequency, prompt, category)
- Generates AI content using Claude (Anthropic API or Claude Code CLI fallback) with web search for up-to-date information
- Writes rich Notion pages with proper formatting (headings, bullets, toggles for quiz answers, quotes, code blocks)
- Tracks everything — live stats callout, per-habit history, period-aware deduplication
Key features
-
Full CLI:
setup,run,add,delete,status,history— manage everything from the terminal - Smart deduplication: daily pages keyed by date, weekly by week number, monthly by month — never generates duplicates
- Rich Notion output: markdown-to-Notion block conversion with headings, bullets, numbered lists, toggles, blockquotes, bold/italic/code
- Live dashboard: a stats callout on your main page updates after each run ("This week: 3 generated | Total: 12 generated")
- Link feed: newest generated pages appear as links on your main RitualFlow page
- API + CLI fallback: uses Anthropic API if available, seamlessly falls back to Claude Code CLI
- Web search: generated content uses live web data (tech news, real places, current facts)
- Built-in templates: tech quiz with toggle answers, fun facts, Paris discovery, weekly tech digest
- GitHub Actions: fully automated scheduling — daily at 8 AM, weekly on Mondays, monthly on the 1st
- Custom prompts: define any prompt you want — RitualFlow is not limited to built-in templates
Demo
Show us the Code
et-POST
/
ritualflow
AI-powered habit automation for Notion — define habits, generate personalized content with Claude, and track everything in a beautiful Notion dashboard. Built for the Notion MCP Challenge.
RitualFlow
AI-powered habit automation for Notion — automatically generate personalized content (quizzes, digests, discoveries...) based on habits you define in a Notion database.
How it works
[Notion DB: Habits] --> [RitualFlow CLI] --> [Notion: Generated Pages]
| |
Anthropic API Notion API
(generation) (read/write)
- Define habits in a Notion database — each with a name, frequency, prompt, and category
- Run RitualFlow — it reads your habits, generates AI content via Claude, and writes rich Notion pages
- Track progress — a live stats callout on your Notion page shows weekly and all-time generation counts
Generated pages are stored as child pages under each habit, with automatic deduplication and a link feed on your main page.
Features
- Smart content generation — custom prompts or built-in templates (tech quiz, fun facts, place discovery, weekly digest)
- Multiple frequencies — daily, weekly, monthly habits with period-aware deduplication
- Anthropic API + CLI fallback — uses the…
Architecture
[Notion DB: Habits] --> [RitualFlow CLI] --> [Notion: Generated Pages]
| |
Anthropic API Notion API
(generation) (read/write)
The project is structured as a clean Python package:
| File | Role |
|---|---|
cli.py |
Click-based CLI with 6 commands |
habits.py |
Reads habit config from Notion DB |
generator.py |
AI content generation (API + CLI fallback) |
writer.py |
Creates rich Notion pages with markdown conversion |
dashboard.py |
Live stats callout management |
setup_notion.py |
One-command Notion workspace setup |
templates.py |
Built-in prompt templates |
utils.py |
Direct Notion API calls via httpx |
The workflow in 4 commands
# 1. Setup — creates database + stats block in Notion
ritualflow setup
# 2. Add habits
ritualflow add "Daily Tech Quiz" --freq daily \
--prompt "Generate a 5-question quiz on a random programming topic" \
--category tech
ritualflow add "Paris Discovery" --freq monthly \
--prompt "Suggest an interesting place to discover in Paris" \
--category wellness
# 3. Run — generates content for all active habits
ritualflow run
# 4. Check status
ritualflow status
Notion output structure
RitualFlow Page
├── [Stats Callout] "This week: 3 generated | Total: 12 generated"
├── [Link] Daily Tech Quiz – 28 mars 2026
├── [Link] Paris Discovery – Mars 2026
└── RitualFlow - Habits (database)
├── Daily Tech Quiz (active, daily)
│ ├── Daily Tech Quiz – 28 mars 2026
│ └── Daily Tech Quiz – 27 mars 2026
└── Paris Discovery (active, monthly)
└── Paris Discovery – Mars 2026
How I Used Notion MCP
Notion MCP is at the core of RitualFlow — it's both the input and the output of the entire workflow.
Reading: Notion as the configuration layer
The habits database is the single source of truth. Users configure everything in Notion — habit names, frequencies, AI prompts, categories, active/inactive toggles. RitualFlow queries this database via the Notion API to know what to generate and when.
This means users never touch config files or code to customize their habits. They just edit a Notion database row.
Writing: Notion as the content destination
Generated content is written as rich child pages under each habit row. The markdown-to-Notion block conversion handles:
- Headings (h1/h2/h3) for structure
-
Toggle blocks from
<details>/<summary>for quiz answers - Bulleted and numbered lists for key points
- Blockquotes for callouts and quotes
- Inline formatting (bold, italic, code) for emphasis
Each page gets a contextual emoji icon based on category, and a human-readable title with the date in French ("Daily Tech Quiz – 28 mars 2026").
Dashboard: Notion as the tracking layer
After each run, RitualFlow updates a stats callout block on the main page with weekly and all-time generation counts. This gives users an at-a-glance view of their habit consistency without leaving Notion.
A link feed on the main page surfaces the most recent generated pages — newest first, right below the stats.
What Notion MCP unlocks
The key insight: Notion becomes the entire application interface. There's no separate UI, no web app, no dashboard to build. Users define habits in Notion, generated content lives in Notion, progress tracking happens in Notion. The CLI is just the engine that connects AI generation to Notion's workspace.
This makes RitualFlow instantly familiar to any Notion user — no learning curve beyond adding a row to a database.
Tech stack: Python 3.11+, Anthropic SDK, notion-client + httpx, Click, python-dotenv
Top comments (0)