loom-plan

Serveur MCP qui donne à Claude Desktop une vue unifiée et actionnable de mon Google Agenda et de mes Google Tasks. Les retards d'abord, puis la journée, les créneaux libres et les tâches ouvertes.

Google reste l'unique référentiel. Le serveur ne stocke rien en dehors du token OAuth et d'un cache de lecture de trente secondes. Claude ne voit jamais un objet Google brut : événements et tâches arrivent dans un seul format, en heure locale, déjà triés dans l'ordre où je veux les lire.

Ce que ça fait

Quand je demande à Claude « qu'est-ce que j'ai aujourd'hui ? », il appelle le tool next et reçoit en un seul aller-retour tout ce qui est en retard, les événements de la journée, les trous entre eux et les tâches ouvertes, datées ou non. Il me présente ça en trois tableaux : En retard, Aujourd'hui, À faire.

Quand je dis « c'est fait », il marque l'événement ou la tâche. Quand je dis « ajoute une tâche pour vendredi », il la crée dans Google Tasks. Il ne fait jamais d'écriture de sa propre initiative : la règle figure dans la description de chaque tool d'écriture.

Quelques principes qui structurent tout le reste. Une chose passée et non traitée continue de remonter tant qu'elle n'est pas marquée faite ou annulée ; le passage du temps ne vaut pas traitement. Une ambiguïté est refusée avec un message clair plutôt que résolue par défaut : modifier une occurrence d'une série récurrente sans dire si on vise l'occurrence ou la série, c'est une erreur, pas une supposition. Une tâche ne bloque pas de temps, elle se fait dans les heures libres. Et le serveur fournit des données déjà ordonnées, la mise en forme finale reste à Claude.

Related MCP server: Schedule MCP Server

Installation

Il faut Python 3.12 ou plus, uv, et un compte Google.

git clone <ce dépôt> ~/dev/loom-plan
cd ~/dev/loom-plan
uv sync

Côté Google Cloud

Une fois, dans la console Google Cloud. Créer un projet, activer les API Google Calendar et Google Tasks. Dans Google Auth Platform, configurer l'écran de consentement en type Externe, ajouter les trois scopes ci-dessous dans Accès aux données, puis, dans Audience, publier l'application. Ce dernier point compte : en statut Test, Google fait expirer le refresh token au bout de sept jours et il faut se réauthentifier chaque semaine. En production sans validation, l'écran « application non vérifiée » s'affiche une fois au consentement et le token devient permanent.

https://www.googleapis.com/auth/calendar.events.owned
https://www.googleapis.com/auth/calendar.calendarlist.readonly
https://www.googleapis.com/auth/tasks

calendar.events.owned ne donne accès qu'aux agendas dont je suis propriétaire. Les abonnements en lecture seule (jours fériés, numéros de semaine) sont ignorés, et le token ne pourrait pas y écrire de toute façon.

Créer ensuite un client OAuth de type Application de bureau, télécharger son JSON et le placer à la racine du dépôt sous le nom client_secret.json. Ce fichier et token.json sont dans le .gitignore.

Configuration

Le serveur lit loom-plan.toml, dont le chemin est donné par la variable LOOM_PLAN_CONFIG ou par l'option --config, sinon dans le répertoire courant. Les chemins relatifs qu'il contient sont résolus par rapport au fichier lui-même.

[auth]
client_secret = "client_secret.json"
token = "token.json"

[general]
timezone = "Europe/Paris"
epoch = 2026-09-13
primary_calendar = "lamard.denis@gmail.com"
default_task_list = "Liste de lamard.denis"
notes_max_chars = 500
cache_ttl_seconds = 30

[work]
start = 09:00:00
end = 18:00:00
days = ["mon", "tue", "wed", "thu", "fri"]

[status]
done_prefix = "[fait]"
cancelled_prefix = "[annulé]"
tracked_prefix = "[suivi]"

L'epoch est la date de mise en service. Rien d'antérieur n'est considéré comme en retard, sinon tout l'historique de l'agenda remonterait au premier appel. Elle ne filtre que les retards : demander l'agenda de mars reste possible.

Premier lancement

uv run loom-plan auth     # ouvre le navigateur pour le consentement Google
uv run loom-plan check    # liste les agendas et les listes Tasks : les trois scopes sont validés d'un coup
uv run loom-plan next

Dans Claude Desktop

Dans claude_desktop_config.json, au même niveau que les autres serveurs :

"loom-plan": {
  "command": "/home/denis/dev/loom-plan/.venv/bin/loom-plan-mcp",
  "args": ["--config", "/home/denis/dev/loom-plan/loom-plan.toml"],
  "env": {}
}

Claude Desktop lance deux instances du serveur (chat et Cowork). Elles partagent token.json ; le rafraîchissement du token est protégé par un verrou fichier, et une instance relit le fichier avant de rafraîchir au cas où l'autre l'aurait déjà fait. Une lecture qui échoue sur un token expiré est retentée une fois.

Les tools

Lecture libre.

Écriture, uniquement sur demande explicite.

Chaque item porte un id qui encode son conteneur, evt_<agenda>/<id> ou task_<liste>/<id>, pour que les écritures sachent où frapper sans état côté serveur.

Les conventions de titre

Google Tasks distingue « à faire » de « terminé » mais pas « terminé » d'« abandonné », et Google Calendar n'a aucune notion de « fait ». Trois préfixes en tête de titre comblent ça. Ils sont retirés à la lecture et traduits en statut ; le serveur les réécrit lui-même à l'écriture.

Sans [suivi], les occurrences récurrentes sont exclues des retards : un point hebdo passé a eu lieu, personne ne le marque fait. Avec, une occurrence oubliée reste visible jusqu'à ce que je la traite, et la marquer faite ne touche que cette occurrence, jamais la série.

Une dernière convention, dans les notes cette fois : ~30min ou ~1h30 donne une durée estimée, utilisée pour trier les tâches du bloc À faire.

Ligne de commande

Les mêmes opérations sont disponibles en CLI, ce qui a servi à valider le mapping sur le vrai compte avant d'écrire le serveur.

uv run loom-plan next
uv run loom-plan overdue
uv run loom-plan agenda 2026-09-14 2026-09-21
uv run loom-plan tasks --status done
uv run loom-plan find notaire
uv run loom-plan free "2026-09-15 09:00" "2026-09-15 18:00" --min 45
uv run loom-plan add-task "Relancer le devis Dupont" --due 2026-09-19 --notes "~15min"
uv run loom-plan add-event "Regarder mon compte Malt" "2026-09-16 09:00" "2026-09-16 09:30" --recurrence "FREQ=WEEKLY;BYDAY=WE" --tracked
uv run loom-plan set-status task_<liste>/<id> done
uv run loom-plan serve     # le serveur MCP en stdio, équivalent de loom-plan-mcp

Quelques détails du mapping

Ce sont les points où Google ne dit pas ce qu'on croit, et qui ont chacun coûté une itération.

Un événement sur la journée entière a chez Google une date de fin exclusive : « du 14 au 17 » signifie du 14 au 16. Le serveur expose le vrai dernier jour et refait la conversion à l'écriture.

L'échéance d'une tâche est renvoyée sous la forme 2026-09-14T00:00:00.000Z, mais l'heure n'a aucun sens. Elle est lue comme une date pure et jamais convertie en heure locale, sinon on décale d'un jour.

Les descriptions d'événements sont en HTML. Les balises sont retirées, les sauts de ligne conservés, les entités décodées, et le tout est tronqué à 500 caractères avec un indicateur.

Un événement annulé n'est plus renvoyé par Google sans showDeleted, et pour un événement simple l'annulation équivaut à une mise à la corbeille. Demander status="cancelled" active ce paramètre.

Sur une récurrence, Google renvoie des occurrences dont l'id est celui de la série suffixé par la date. Marquer une occurrence faite crée une exception de la série, ce qui est exactement le comportement voulu.

Développement

uv run pytest -q
uv run ruff check src tests
uv run pyright

Les tests couvrent le mapping sur des payloads Google figés, le service avec les API Google simulées au niveau HTTP (respx), et le contrat des tools exposés par le serveur. Pyright est en mode strict ; les bibliothèques Google n'étant pas typées, une façade Protocol isole la frontière dans auth.py.

La spec complète, avec les décisions prises et leur justification, est dans spec-loom-plan.md.

Ce qui n'est pas là

Pas d'interface HTML interactive. Le crochet MCP Apps est en place (le tool next déclare une ressource ui://loom-plan/next.html), mais Claude Desktop ne rend pas encore les interfaces des serveurs personnalisés, ce qui est un bug connu de son côté. Le jour où ça change, la page minimale s'affichera d'elle-même et il sera temps d'écrire la vraie vue.

Pas de déclencheur d'actions automatiques, pas de synchronisation locale, pas d'agendas partagés tiers. Un seul agenda pour l'instant, mais le format des ids est prêt pour en ajouter un second sans migration.

Licence

Apache 2.0.