morgen-mcp 0.1.0

package/.env.example

@@ -0,0 +1,5 @@
+# Morgen API key — get one at https://platform.morgen.so/developers-api
+MORGEN_API_KEY=
+
+# IANA timezone for calendar operations (default: America/New_York)
+MORGEN_TIMEZONE=America/New_York

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathan Davidovich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+# Morgen MCP
+
+**Natural-language calendar and task control for Morgen in Claude Code.**
+
+[![npm version](https://img.shields.io/npm/v/morgen-mcp)](https://www.npmjs.com/package/morgen-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green)](https://modelcontextprotocol.io)
+
+---
+
+## How It Works
+
+Once installed, you just talk to Claude. No commands to memorize, no special syntax, no API calls to learn. You speak in plain English and Claude handles the rest.
+
+```
+You:    "What's on my calendar this week?"
+You:    "Add a task called 'Review contracts' due Friday, high priority"
+You:    "Move my 3pm to 4pm tomorrow"
+You:    "Mark the laundry task as done"
+You:    "Decline the 5pm invite"
+You:    "Create a 30-minute call with drew@example.com Thursday at 2pm"
+```
+
+That's it. Claude sees your Morgen calendars and tasks, understands your schedule, and takes action -- all through natural conversation. No buttons, no UI, no context switching. You stay in your terminal and your day stays in sync.
+
+---
+
+## Why This Exists
+
+Morgen is one of the cleanest calendar-plus-task apps on the market. It unifies Google, Outlook, iCloud, and native tasks into a single auto-scheduling interface, and it ships a genuinely well-designed public API.
+
+This MCP wraps that API and hands the whole surface to Claude Code -- events, tasks, RSVPs, calendars, the lot. One API key, one install command, and you are talking to your calendar in natural language.
+
+Unlike other calendar integrations that require extracting refresh tokens from browser storage or juggling multiple credentials, Morgen uses a single API key. You grab it from their developer portal, drop it in the config, and you are done.
+
+## Features
+
+### Event Tools
+
+| Tool | Description |
+|---|---|
+| `list_calendars` | List all Morgen calendars with id, name, color, account, sort order, and read-only status |
+| `list_events` | Fetch events in a date range across one or more calendars with full details |
+| `create_event` | Create an event with title, time, participants, description, location, and recurrence |
+| `update_event` | Update an event; supports `seriesUpdateMode` for editing recurring events (this, following, all) |
+| `delete_event` | Delete an event by ID |
+| `rsvp_event` | Accept, decline, or tentatively respond to an invitation |
+
+### Task Tools
+
+| Tool | Description |
+|---|---|
+| `list_tasks` | List native Morgen tasks |
+| `create_task` | Create a new task with title, description, due date, and priority (integer 0-9; 1 = highest, 9 = lowest) |
+| `update_task` | Update an existing task -- change title, description, due date, or priority |
+| `move_task` | Move a task to a different list |
+| `close_task` | Mark a task as completed |
+| `reopen_task` | Reopen a completed task |
+| `delete_task` | Delete a task permanently |
+
+## Important Note About Tasks
+
+Morgen's `/tasks` endpoints only manage **first-party native Morgen tasks** -- the ones created directly inside Morgen with `integrationId: "morgen"`. Tasks that Morgen syncs in from external providers like Todoist, Google Tasks, Microsoft To Do, or Things are fully visible in the Morgen app but are **not writable through this MCP**. The Morgen API intentionally scopes write access to its own first-party task system.
+
+The practical takeaway: if you want Claude to create, update, and close tasks programmatically, create them as native Morgen tasks. Everything else stays read-only from Morgen's side and should be managed through that provider's own integration.
+
+## Quick Install
+
+One command. That is it.
+
+```bash
+claude mcp add morgen --env MORGEN_API_KEY=your_key_here -- npx -y morgen-mcp
+```
+
+Then restart Claude Code and start talking to your calendar.
+
+## Setup
+
+Morgen authentication is simple: one API key. No browser scraping, no refresh tokens, no Firebase.
+
+### Step 1: Get your Morgen API key
+
+1. Go to [platform.morgen.so/developers-api](https://platform.morgen.so/developers-api)
+2. Sign in with your Morgen account
+3. Generate an API key and copy it
+
+### Step 2: Configure
+
+You have two options:
+
+**Option A -- Run the setup command:**
+
+```bash
+npx morgen-mcp setup
+```
+
+It will prompt you for your API key and timezone, then write a `.env` file for you.
+
+**Option B -- Create `.env` manually:**
+
+```bash
+MORGEN_API_KEY=your_morgen_api_key_here
+MORGEN_TIMEZONE=America/New_York
+```
+
+Or pass them as environment variables in your Claude MCP config:
+
+```json
+{
+  "mcpServers": {
+    "morgen": {
+      "command": "npx",
+      "args": ["-y", "morgen-mcp"],
+      "env": {
+        "MORGEN_API_KEY": "your_morgen_api_key_here",
+        "MORGEN_TIMEZONE": "America/New_York"
+      }
+    }
+  }
+}
+```
+
+### Step 3: Restart Claude Code
+
+That is the whole setup. No token refresh cycles, no IndexedDB spelunking.
+
+## Configuration Reference
+
+| Variable | Required | Description |
+|---|---|---|
+| `MORGEN_API_KEY` | Yes | Your Morgen API key from [platform.morgen.so/developers-api](https://platform.morgen.so/developers-api) |
+| `MORGEN_TIMEZONE` | No | IANA timezone for calendar operations (default: `America/New_York`). Used for formatting event times and task due dates. |
+
+## Usage Examples
+
+Once installed and configured, just talk to Claude naturally:
+
+**Check your schedule**
+> "What's on my calendar this week?"
+
+**List calendars**
+> "Which Morgen calendars do I have connected?"
+
+**Create events**
+> "Create a meeting called 'Team Sync' tomorrow at 2pm for 30 minutes"
+> "Schedule a call with drew@example.com at 5:30pm today"
+
+**Modify events**
+> "Move my 3pm to 4pm"
+> "Change the Team Sync description to include the agenda link"
+
+**Handle invitations**
+> "Decline the 5pm meeting"
+> "Tentatively accept the all-hands on Thursday"
+
+**Delete events**
+> "Cancel the standup on Friday"
+
+**Manage tasks**
+> "Add a task called 'Review contracts' due Friday, high priority"
+> "What tasks do I have open?"
+> "Mark the laundry task as done"
+> "Reopen the invoice follow-up task"
+> "Move the recording task to my Deep Work list"
+
+## Rate Limits
+
+Morgen uses a rolling point-based rate limit: **100 points per 15-minute window** per API key.
+
+- List endpoints (`list_events`, `list_tasks`, `list_calendars`) cost **10 points** per call
+- Writes (create, update, delete, close, reopen, rsvp, move) cost **1 point** per call
+
+In practice this is generous for interactive use -- you can fire off dozens of writes in a session without getting near the ceiling. Just avoid tight polling loops on the list endpoints.
+
+Full details: [docs.morgen.so/rate-limits](https://docs.morgen.so/rate-limits)
+
+## Security
+
+Your Morgen API key grants full access to your Morgen account -- all calendars, all events, all tasks. Treat it like a password:
+
+- Do not commit your `.env` file to version control. The included `.gitignore` excludes it, but verify.
+- Do not paste your key into shared chats, issues, or screenshots.
+- Rotate the key from the developer portal if you suspect it has leaked.
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/lorecraft-io/morgen-mcp.git
+cd morgen-mcp
+
+# Install dependencies
+npm install
+
+# Configure credentials
+cp .env.example .env
+# Edit .env with your API key
+
+# Run directly
+npm start
+```
+
+## Under the Hood
+
+The server runs as a stdio-based MCP server using the official `@modelcontextprotocol/sdk`. All Morgen operations go through raw `fetch` calls against the public API at `https://api.morgen.so/v3`, authenticated with your API key via the `Authorization: ApiKey ...` header.
+
+No SDK middleware, no token juggling, no refresh cycles. Just a thin, predictable wrapper around endpoints that Morgen already documents.
+
+## License
+
+MIT -- see [LICENSE](LICENSE) for details.
+
+---
+
+Built by [Nathan Davidovich / Lorecraft](https://github.com/lorecraft-io)

package/bin/setup.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+import { createInterface } from "readline";
+import { writeFileSync, existsSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const envPath = resolve(__dirname, "..", ".env");
+
+const rl = createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+function ask(question, defaultValue) {
+  return new Promise((resolve) => {
+    const prompt = defaultValue
+      ? `${question} (${defaultValue}): `
+      : `${question}: `;
+    rl.question(prompt, (answer) => {
+      resolve(answer.trim() || defaultValue || "");
+    });
+  });
+}
+
+async function main() {
+  console.log("");
+  console.log("===========================================");
+  console.log("  Morgen MCP - Setup Wizard");
+  console.log("===========================================");
+  console.log("");
+
+  if (existsSync(envPath)) {
+    const overwrite = await ask(
+      "A .env file already exists. Overwrite? (y/N)",
+      "N"
+    );
+    if (overwrite.toLowerCase() !== "y") {
+      console.log("\nSetup cancelled. Existing .env file preserved.");
+      rl.close();
+      return;
+    }
+    console.log("");
+  }
+
+  console.log("You'll need the following credential.");
+  console.log("See the README for detailed instructions on where to find it.");
+  console.log("");
+
+  const morgenApiKey = await ask(
+    "Morgen API key (from https://platform.morgen.so/developers-api)"
+  );
+
+  if (!morgenApiKey) {
+    console.error("\nMorgen API key is required. Setup cancelled.");
+    rl.close();
+    process.exit(1);
+  }
+
+  const timezone = await ask("Timezone", "America/New_York");
+
+  const envContent = `# Morgen MCP Configuration
+# Generated by setup wizard
+
+MORGEN_API_KEY=${morgenApiKey}
+MORGEN_TIMEZONE=${timezone}
+`;
+
+  writeFileSync(envPath, envContent, { mode: 0o600 });
+
+  console.log("");
+  console.log("===========================================");
+  console.log("  Setup complete!");
+  console.log("===========================================");
+  console.log("");
+  console.log(`  .env written to: ${envPath}`);
+  console.log("");
+  console.log("  Next steps:");
+  console.log("  1. Add the MCP server to your Claude config:");
+  console.log("");
+  console.log("     claude mcp add morgen -- npx -y morgen-mcp");
+  console.log("");
+  console.log("  2. Or run directly:");
+  console.log("");
+  console.log("     npm start");
+  console.log("");
+
+  rl.close();
+}
+
+main().catch((err) => {
+  console.error("Setup failed:", err.message);
+  rl.close();
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "morgen-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Morgen — events, tasks, and calendar management for Claude Code via natural language",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "morgen-mcp": "src/index.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    ".env.example",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "setup": "node bin/setup.js",
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": ["mcp", "morgen", "calendar", "tasks", "claude", "ai", "productivity", "scheduling"],
+  "author": "Nathan Davidovich <nate@lorecraft.io>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lorecraft-io/morgen-mcp"
+  },
+  "homepage": "https://github.com/lorecraft-io/morgen-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "dotenv": "17.4.0"
+  },
+  "devDependencies": {
+    "vitest": "4.1.2"
+  }
+}

package/src/client.js

@@ -0,0 +1,136 @@
+export const MORGEN_BASE = "https://api.morgen.so";
+
+const RATE_LIMIT_POINTS = 100;
+const RATE_LIMIT_WINDOW_MS = 15 * 60 * 1000;
+
+// Rolling window of { timestamp, points } entries
+let pointLedger = [];
+
+function pruneLedger(now) {
+  const cutoff = now - RATE_LIMIT_WINDOW_MS;
+  pointLedger = pointLedger.filter((entry) => entry.timestamp > cutoff);
+}
+
+function currentPoints() {
+  return pointLedger.reduce((sum, entry) => sum + entry.points, 0);
+}
+
+// Walk the ledger to find the earliest moment enough old points expire
+// for the incoming request to fit within the budget. A 10-point list call
+// with only 5 free points needs to wait until multiple old entries drop off,
+// not just the oldest one.
+function msUntilFits(now, incomingPoints) {
+  const overBy = currentPoints() + incomingPoints - RATE_LIMIT_POINTS;
+  if (overBy <= 0) return 0;
+  let released = 0;
+  for (const entry of pointLedger) {
+    released += entry.points;
+    if (released >= overBy) {
+      const expiryTime = entry.timestamp + RATE_LIMIT_WINDOW_MS;
+      return Math.max(0, expiryTime - now);
+    }
+  }
+  return RATE_LIMIT_WINDOW_MS;
+}
+
+function enforceRateLimit(points) {
+  const now = Date.now();
+  pruneLedger(now);
+
+  if (currentPoints() + points > RATE_LIMIT_POINTS) {
+    const msUntilExpiry = msUntilFits(now, points);
+    const secondsUntilExpiry = Math.max(1, Math.ceil(msUntilExpiry / 1000));
+    throw new Error(
+      `Morgen rate limit reached (100 points per 15 minutes). Try again in ${secondsUntilExpiry} seconds.`
+    );
+  }
+
+  pointLedger.push({ timestamp: now, points });
+}
+
+export function _resetRateLimiter() {
+  pointLedger = [];
+}
+
+function fetchWithTimeout(url, options = {}, timeoutMs = 30_000) {
+  const controller = new AbortController();
+  const id = setTimeout(() => controller.abort(), timeoutMs);
+  return fetch(url, { ...options, signal: controller.signal }).finally(() => clearTimeout(id));
+}
+
+async function withRetry(fn, maxAttempts = 3) {
+  let lastError;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      const isRetryable =
+        err.name === "AbortError" ||
+        (err.message && (
+          err.message.includes("HTTP 429") ||
+          err.message.includes("HTTP 503") ||
+          err.message.includes("fetch failed")
+        ));
+      if (!isRetryable || attempt === maxAttempts) throw err;
+      await new Promise((r) => setTimeout(r, 1_000 * attempt));
+    }
+  }
+  throw lastError;
+}
+
+function morgenHeaders() {
+  const apiKey = process.env.MORGEN_API_KEY;
+  return {
+    Authorization: `ApiKey ${apiKey}`,
+    Accept: "application/json",
+    "Content-Type": "application/json",
+  };
+}
+
+function scrubKey(message) {
+  const key = process.env.MORGEN_API_KEY;
+  if (!message) return message;
+  let scrubbed = message.replace(/https?:\/\/[^\s)]+/g, "[redacted-url]");
+  if (key && key.length > 4) {
+    scrubbed = scrubbed.split(key).join("[redacted-key]");
+  }
+  return scrubbed;
+}
+
+export async function morgenFetch(path, { method = "GET", body, points = 1 } = {}) {
+  enforceRateLimit(points);
+
+  try {
+    return await withRetry(async () => {
+      const init = {
+        method,
+        headers: morgenHeaders(),
+      };
+      if (body !== undefined) {
+        init.body = JSON.stringify(body);
+      }
+
+      const res = await fetchWithTimeout(`${MORGEN_BASE}${path}`, init);
+
+      if (!res.ok) {
+        throw new Error(
+          `Morgen API error (HTTP ${res.status}). The request to ${path} was not successful.`
+        );
+      }
+
+      if (
+        res.status === 204 ||
+        res.status === 205 ||
+        res.headers.get("content-length") === "0"
+      ) {
+        return null;
+      }
+
+      return res.json();
+    });
+  } catch (err) {
+    const safe = scrubKey(err instanceof Error ? err.message : String(err));
+    throw new Error(safe || "Morgen API call failed");
+  }
+}

package/src/events-shape.js

@@ -0,0 +1,129 @@
+// Pure helpers for shaping Morgen event/calendar API responses and
+// building request bodies. Kept separate from tools-events.js to
+// respect the 500-line-per-file project rule.
+import { validateStringArray } from "./validation.js";
+
+export const MAX_DESCRIPTION_LEN = 5000;
+export const MAX_PARTICIPANTS = 100;
+export const MAX_RECURRENCE_RULES = 20;
+
+export function validateParticipantEmails(value, field = "participants") {
+  validateStringArray(value, field, MAX_PARTICIPANTS);
+  const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  for (const entry of value) {
+    if (!emailPattern.test(entry)) {
+      throw new Error(`${field} entries must be valid email addresses`);
+    }
+  }
+}
+
+// Morgen expects participants as a keyed map:
+// { <id>: { @type, email, roles, participationStatus } }.
+// At creation we don't have server IDs yet, so key by email — the server
+// assigns real IDs. Default each participant to attendee / needs-action.
+export function toParticipantMap(emails = []) {
+  const map = {};
+  for (const email of emails) {
+    map[email] = {
+      "@type": "Participant",
+      email,
+      roles: { attendee: true },
+      participationStatus: "needs-action",
+    };
+  }
+  return map;
+}
+
+export function validateRecurrenceRules(value, field = "recurrence_rules") {
+  if (!Array.isArray(value)) {
+    throw new Error(`${field} must be an array of recurrence rule objects`);
+  }
+  if (value.length > MAX_RECURRENCE_RULES) {
+    throw new Error(`${field} exceeds maximum of ${MAX_RECURRENCE_RULES} rules`);
+  }
+  for (const rule of value) {
+    if (!rule || typeof rule !== "object" || Array.isArray(rule)) {
+      throw new Error(
+        `${field} entries must be objects (e.g. { "@type": "RecurrenceRule", "frequency": "weekly", "interval": 1 })`
+      );
+    }
+    if (!rule.frequency || typeof rule.frequency !== "string") {
+      throw new Error(`${field} entries must include a "frequency" string`);
+    }
+  }
+  return value;
+}
+
+function deriveOrganizer(participants) {
+  if (!participants || typeof participants !== "object") return undefined;
+  for (const key of Object.keys(participants)) {
+    const p = participants[key];
+    if (p && p.roles && p.roles.owner === true) {
+      return p.email || p.name || key;
+    }
+  }
+  return undefined;
+}
+
+function mapParticipants(participants) {
+  if (!participants || typeof participants !== "object") return undefined;
+  const entries = Array.isArray(participants)
+    ? participants
+    : Object.values(participants);
+  return entries.map((p) => ({
+    email: p?.email,
+    name: p?.name,
+    participationStatus: p?.participationStatus,
+    isOrganizer: p?.roles?.owner === true,
+    isAttendee: p?.roles?.attendee === true,
+  }));
+}
+
+export function mapEvent(e) {
+  if (!e || typeof e !== "object") return e;
+  return {
+    id: e.id,
+    title: e.title,
+    start: e.start,
+    end: e.end,
+    calendarId: e.calendarId,
+    description:
+      typeof e.description === "string"
+        ? e.description.substring(0, MAX_DESCRIPTION_LEN)
+        : undefined,
+    location: e.location,
+    participants: mapParticipants(e.participants),
+    organizer: deriveOrganizer(e.participants),
+    recurrenceRules: e.recurrenceRules,
+    seriesId: e.seriesId,
+  };
+}
+
+export function mapCalendar(c) {
+  if (!c || typeof c !== "object") return c;
+  const rights = c.myRights || {};
+  const readOnly = rights.mayWriteAll === false && rights.mayReadItems === true;
+  return {
+    id: c.id,
+    name: c.name,
+    color: c.color,
+    accountId: c.accountId,
+    integrationId: c.integrationId,
+    sortOrder: c.sortOrder,
+    readOnly,
+  };
+}
+
+// Morgen wraps all responses in { data: { ... } }.
+// See https://docs.morgen.so/calendars and https://docs.morgen.so/events
+export function unwrapCalendars(data) {
+  return data?.data?.calendars ?? data?.calendars ?? [];
+}
+
+export function unwrapEvents(data) {
+  return data?.data?.events ?? data?.events ?? [];
+}
+
+export function unwrapEvent(data) {
+  return data?.data?.event ?? data?.event ?? data?.data ?? data;
+}