TaskFlow

TaskFlow is a local Model Context Protocol (MCP) server for personal tasks and schedules. Claude Code interprets requests such as “remind me to submit expenses tomorrow” and calls TaskFlow's structured tools. TaskFlow owns validation, business rules, and SQLite persistence.

TaskFlow deliberately does not store journal entries. On macOS it can mirror tasks one way into Apple Reminders and events one way into Apple Calendar. Google Calendar is not connected.

What it provides

• Create, list, update, complete, and delete tasks
• Low, medium, and high task priorities
• Pending, in-progress, completed, and cancelled task states
• Due-date filtering and text search
• One-way task synchronization from TaskFlow to Apple Reminders on macOS
• Create, list, update, and delete scheduled events
• Add one or more explicit alerts to scheduled events
• One-way event synchronization from TaskFlow to Apple Calendar on macOS
• Event-window filtering with correct overlap behavior
• Local SQLite storage with no external account or database
• Validation for IDs, text lengths, enum values, and event time ranges

Architecture

Natural-language request
        ↓
Claude Code
        ↓ MCP tool call
taskflow/server.py          MCP interface
        ↓
taskflow/service.py         business rules and validation
        ├─→ taskflow/database.py → data/taskflow.db
        ├─→ Apple Reminders adapter → osascript → Reminders.app/iCloud
        └─→ Apple Calendar adapter → osascript → Calendar.app/iCloud

The language model handles natural-language interpretation. TaskFlow does not embed an LLM or attempt to parse phrases like “next Friday” itself.

Requirements

• Python 3.11 or newer
• uv
• Claude Code, or another MCP client that supports stdio servers

Install and test

uv sync
uv run pytest

Run the server directly over stdio:

TASKFLOW_DB_PATH=./data/taskflow.db uv run taskflow

The process waits for MCP messages on standard input; it is normal for it to appear idle when started manually.

Connect Claude Code

The repository includes a project-scoped .mcp.json. Open Claude Code in this directory, approve the taskflow server when prompted, then check it with:

claude mcp get taskflow

To register it manually instead, replace both paths below with the absolute project path:

claude mcp add --scope project taskflow \
  -e TASKFLOW_DB_PATH=/absolute/path/to/taskflow/data/taskflow.db \
  -e TASKFLOW_APPLE_CALENDAR_ENABLED=true \
  -e TASKFLOW_APPLE_CALENDAR_NAME=TaskFlow \
  -e TASKFLOW_APPLE_REMINDERS_ENABLED=true \
  -e TASKFLOW_APPLE_REMINDERS_LIST_NAME=TaskFlow \
  -- uv run --directory /absolute/path/to/taskflow taskflow

Example Claude requests:

• “Add a high-priority task to submit my expense report tomorrow at 4 PM.”
• “What tasks are still pending this week?”
• “Mark task 12 as completed.”
• “Schedule a project review next Tuesday from 10 to 11 at the office.”
• “Schedule a project review and alert me one day and one hour before.”
• “What is on my schedule tomorrow?”

Enable Apple Reminders synchronization

The included .mcp.json already enables the macOS adapter and targets a Reminders list named TaskFlow.

1. Open Reminders.app.
2. Create a list named exactly TaskFlow under iCloud or “On My Mac.”
3. Restart Claude Code so the MCP server reloads its configuration.
4. Ask Claude to create a test task with a due date and time.
5. Accept the macOS prompt allowing the requesting app to control Reminders.

This prototype is outbound-only:

Claude/TaskFlow → Reminders.app → iCloud and your Apple devices

New tasks created through TaskFlow are mirrored to Reminders. Updating, completing, reopening, or deleting those TaskFlow tasks makes the same change in Reminders. Edits made directly in Reminders do not return to TaskFlow, and list_tasks reads SQLite.

A task's due_at becomes both its due time and alert time in Reminders. macOS/iOS delivers the notification according to your Reminders notification settings. Tasks without due_at have no time-based alert. TaskFlow maps high, medium, and low priorities to the equivalent Apple priority levels.

Each synchronized task reports sync_status using the same synced, pending, failed, and local meanings described for Calendar below. Existing tasks created before this integration remain local; create a new task through TaskFlow to synchronize it.

See Apple Reminders prototype for field mappings and troubleshooting.

Enable Apple Calendar synchronization

The included .mcp.json already enables the macOS adapter and targets a calendar named TaskFlow.

1. Open Calendar.app.
2. Create a writable calendar named exactly TaskFlow under iCloud or “On My Mac.”
3. Restart Claude Code so the MCP server reloads its configuration.
4. Ask Claude to create a test event.
5. Accept the macOS prompt allowing the requesting app to control Calendar.

If permission was previously denied, open System Settings → Privacy & Security → Automation and allow Calendar access for Claude, Terminal, or the Python process shown there.

This prototype is outbound-only:

Claude/TaskFlow → Calendar.app → iCloud and your Apple devices

Events created, changed, or deleted through TaskFlow are mirrored to Calendar. Edits made directly in Calendar do not return to TaskFlow. TaskFlow remains the source of truth and list_events reads SQLite.

TaskFlow also mirrors its explicit alert list into Calendar display alerts. Updating an event replaces its Calendar alerts with the list stored by TaskFlow.

Each event reports sync_status:

• synced — Apple Calendar accepted the change.
• pending — synchronization is in progress.
• failed — the local event was preserved and sync_error explains the problem.
• local — the event was created while Apple Calendar integration was disabled.

TaskFlow puts a private taskflow://event/<id> marker in the Calendar event URL field. That makes create retries idempotent and helps avoid duplicate Calendar events.

See Apple Calendar prototype for behavior and troubleshooting.

MCP tools

Tool	Purpose
create_task	Create a task with an optional description, due time, and priority
list_tasks	Filter tasks by status, priority, due-time range, or text
update_task	Change task fields or status; can explicitly clear description/due time
delete_task	Permanently delete a task
create_event	Create a timed or all-day event
list_events	List events overlapping a time window or matching text
update_event	Change event details while enforcing a valid time range
delete_event	Permanently delete an event

Task statuses are pending, in_progress, completed, and cancelled. Priorities are low, medium, and high.

Event alerts use alert_minutes_before, a list of whole minutes before the event starts:

Alert	Value
At event time	0
15 minutes before	15
1 hour before	60
1 day before	1440

[15, 60, 1440] creates three alerts. During an update, omitting the field leaves alerts unchanged; passing [] removes all TaskFlow-managed alerts.

Time handling

Tool timestamps must be ISO 8601 values containing a timezone offset or Z:

2026-07-15T15:00:00-06:00
2026-07-15T21:00:00Z

TaskFlow normalizes timestamps to UTC before storing them. Claude Code should resolve relative phrases using the user's local timezone before calling a tool. Naive timestamps such as 2026-07-15T15:00:00 are rejected because they are ambiguous.

Data and configuration

TASKFLOW_DB_PATH controls the SQLite file location. If unset, TaskFlow uses:

~/.local/share/taskflow/taskflow.db

The included Claude Code configuration sets it to ./data/taskflow.db. The data/ database files are ignored by Git.

Apple Calendar settings:

Variable	Default	Purpose
TASKFLOW_APPLE_CALENDAR_ENABLED	false	Enables outbound Calendar synchronization
TASKFLOW_APPLE_CALENDAR_NAME	TaskFlow	Exact writable calendar name to target

Apple Reminders settings:

Variable	Default	Purpose
TASKFLOW_APPLE_REMINDERS_ENABLED	false	Enables outbound Reminders synchronization
TASKFLOW_APPLE_REMINDERS_LIST_NAME	TaskFlow	Exact Reminders list name to target

SQLite uses write-ahead logging and a busy timeout for safe local access. The schema is created automatically the first time the server runs.

Project structure

taskflow/
├── database.py                SQLite schema and connection handling
├── integrations/
│   ├── apple_calendar.py      Python automation adapter
│   ├── apple_calendar.js      Calendar.app JXA operations
│   ├── apple_reminders.py     Python automation adapter
│   ├── apple_reminders.js     Reminders.app JXA operations
│   └── base.py                integration interface
├── server.py                  MCP server and eight tool definitions
├── service.py                 task/event business logic
└── validation.py              shared normalization and validation
tests/                service, validation, and MCP tool tests
.mcp.json             project-scoped Claude Code configuration
CLAUDE.md             guidance for Claude's use of TaskFlow
pyproject.toml        Python package and dependency configuration

Deliberately deferred

• Two-way Apple Calendar synchronization
• Two-way Apple Reminders synchronization
• Google Calendar integration
• Schedule conflict detection
• Recurring tasks and events
• Multi-user accounts or remote sync

These can be added behind separate adapter modules without moving business rules into Claude prompts. A personal journal should remain its own MCP service.