MCP 服务器

voiceos-todoist

Enables voice control of Todoist tasks via VoiceOS, with optional Apple Reminders to Todoist sync.

README

Todoist for VoiceOS

Voice-control Todoist from VoiceOS — and optionally keep Apple Reminders in sync with it.

A local Model Context Protocol server that adds Todoist to VoiceOS, plus a one-way Apple Reminders → Todoist sync. Your API token stays on your Mac — nothing is sent anywhere except Todoist's own API.

🎙️  "Add buy milk to Todoist tomorrow at 9am"
🎙️  "What's on my Todoist for today?"
🎙️  "Mark the expenses task done"

✨ Features

Add / list / complete / update tasks by voice
Natural-language due dates — "tomorrow at 9am", "every friday"
Priorities (p1–p4), projects, and filters ("today", "overdue")
Fuzzy completion — "mark the milk task done" matches Buy milk
Optional Reminders sync — anything you drop in Apple Reminders lands in Todoist
One-command installer with guided token setup
No keys in code — token lives at ~/.config/todoist/token (chmod 600)

🚀 Quick start

git clone https://github.com/gabeperez/voiceos-todoist.git
cd voiceos-todoist
./setup.sh

The installer will:

Walk you through getting your Todoist API token and validate + save it securely.
Install dependencies.
Register the integration in VoiceOS automatically.
Optionally set up the Reminders → Todoist sync (with a dry-run preview first).

Then restart VoiceOS (or toggle the Todoist integration) and start talking.

Prefer not to clone? Grab todoist-voiceos.zip from the latest release, unzip, and run ./setup.sh.

📋 Requirements


OS	macOS with VoiceOS installed
Runtime	Node.js 18+ (setup checks for it)
Account	A Todoist account

Getting your API token

Todoist → Settings → Integrations → Developer → API token (https://app.todoist.com/app/settings/integrations/developer). The setup script links you straight there and validates the token before saving.

🛠️ Tools

Tool	What it does
`add_task`	Create a task — NL due date, priority p1–p4, project, description.
`list_tasks`	List active tasks; filter by project or query (`today`, `overdue`).
`complete_task`	Close a task by id or content substring (`milk` → `Buy milk`).
`update_task`	Change text / due date / priority / description.
`list_projects`	List your projects and their ids.

Priority is UI-style: p1 = highest, p4 = none.

🔁 Apple Reminders → Todoist sync (optional)

Mirrors incomplete reminders into Todoist on a 5-minute timer:

Due dates + notes are copied; each Reminders list maps to a Todoist project (auto-created).
Dedupe + completion state in ~/.config/todoist/sync-state.json.
When a synced reminder is completed or removed, its Todoist task is closed.
One-way only — Todoist changes never flow back to Reminders.

npm run sync:dry            # preview what would sync — writes nothing
sync/install-launchd.sh     # enable the 5-minute background timer
sync/uninstall-launchd.sh   # stop it

The first run triggers a macOS Automation → Reminders permission prompt — approve it.

Sync options

Set these in sync/run-sync.sh:

Env	Effect
`SYNC_LISTS="Inbox,Work"`	Only sync these Reminders lists (default: all).
`TODOIST_PROJECT="Inbox"`	Force everything into one project (default: list→project).
`SYNC_COMPLETIONS="false"`	Don't close Todoist tasks on completion/removal.
`SYNC_DUE="false"`	Don't copy due dates.
`DRY_RUN="true"`	Report what would sync; write nothing.

🧹 Uninstall

./uninstall.sh

Unregisters from VoiceOS, stops the sync timer, and offers to delete your saved token + state.

🔍 How it works

                 ┌───────────────────────────┐
   VoiceOS ──────►  mcp-server.ts (stdio)     ├──► Todoist API v1
   (voice)        └───────────────────────────┘
                 ┌───────────────────────────┐
 Apple Reminders─►  sync (launchd, every 5m)  ├──► Todoist API v1
                 └───────────────────────────┘

mcp-server.ts — the MCP server VoiceOS launches over stdio (via start.sh).
sync/sync-reminders-to-todoist.mjs — reads Reminders via JXA, pushes to Todoist.
register-voiceos.mjs — adds/removes the entry in VoiceOS's config.json.
Uses the Todoist unified API v1 (/api/v1); the old /rest/v2 is deprecated.

🔒 Privacy

Your token is stored locally at ~/.config/todoist/token (chmod 600) and used only to call Todoist's API directly from your Mac. Nothing is proxied through any third party. The Reminders sync reads your local Reminders via macOS scripting and writes only to your Todoist.