apple-reminders-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,90 @@
+# remindctl-mcp
+
+MCP server for Apple Reminders via [`remindctl`](https://github.com/nicklama/remindctl) CLI. Say "remind me to deploy on Friday" in Claude Code and your iPhone buzzes.
+
+## Prerequisites
+
+- **macOS 14+**
+- **Node.js 18+**
+- **remindctl** installed and authorized:
+
+```bash
+brew install steipete/tap/remindctl
+remindctl authorize
+```
+
+## Install
+
+```bash
+git clone https://github.com/namearth5005/remindctl-mcp.git
+cd remindctl-mcp
+npm install
+npm run build
+```
+
+## Claude Code Configuration
+
+Add to `~/.claude/settings.local.json`:
+
+```json
+{
+  "mcpServers": {
+    "apple-reminders": {
+      "command": "node",
+      "args": ["/absolute/path/to/remindctl-mcp/dist/index.js"],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+Then restart Claude Code.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `add_reminder` | Add a reminder with optional due date, list, notes, priority |
+| `show_reminders` | Show reminders (today, tomorrow, week, overdue, upcoming, all) |
+| `list_reminder_lists` | List all reminder lists or show contents of a specific list |
+| `edit_reminder` | Edit title, due date, notes, priority, or move to another list |
+| `complete_reminders` | Mark one or more reminders as complete |
+| `delete_reminders` | Permanently delete reminders |
+| `manage_reminder_list` | Create, rename, or delete reminder lists |
+
+## Usage Examples
+
+```
+"remind me to deploy the API on Friday at 3pm"
+"what's on my list for today?"
+"mark the deploy reminder as done"
+"show me all overdue tasks"
+"create a new list called Sprint 12"
+"delete the test reminder"
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `REMINDCTL_PATH` | Custom path to remindctl binary (defaults to PATH lookup) |
+
+## Troubleshooting
+
+**"remindctl is not authorized"** — Run `remindctl authorize` and grant Reminders access in System Settings.
+
+**"Could not find remindctl"** — Install via Homebrew: `brew install steipete/tap/remindctl`, or set `REMINDCTL_PATH`.
+
+**Tools not showing in Claude Code** — Restart Claude Code after adding the MCP server config. Check `~/.claude/settings.local.json` for correct absolute path.
+
+**Using nvm?** MCP stdio servers don't load nvm. Use the full node path in your config:
+
+```json
+"command": "/opt/homebrew/bin/node"
+```
+
+Find yours with: `readlink -f $(which node)` or `ls /opt/homebrew/bin/node`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { promisify } from "node:util";
+import { z } from "zod";
+const execFileAsync = promisify(execFile);
+// ---------------------------------------------------------------------------
+// Resolve remindctl binary
+// ---------------------------------------------------------------------------
+function resolveRemindctl() {
+    if (process.env.REMINDCTL_PATH)
+        return process.env.REMINDCTL_PATH;
+    // MCP stdio servers often inherit a minimal PATH that excludes Homebrew.
+    // Check common install locations explicitly.
+    const candidates = [
+        "/opt/homebrew/bin/remindctl", // Apple Silicon
+        "/usr/local/bin/remindctl", // Intel Mac
+    ];
+    for (const path of candidates) {
+        if (existsSync(path))
+            return path;
+    }
+    // Fall back to PATH lookup
+    return "remindctl";
+}
+const REMINDCTL = resolveRemindctl();
+async function runRemindctl(args) {
+    const fullArgs = [...args, "--json", "--no-input"];
+    try {
+        const { stdout } = await execFileAsync(REMINDCTL, fullArgs, {
+            timeout: 10_000,
+            env: { ...process.env, NO_COLOR: "1" },
+        });
+        return stdout;
+    }
+    catch (err) {
+        const e = err;
+        const parts = [];
+        if (e.killed)
+            parts.push("process timed out (10s limit)");
+        else if (e.code === "ENOENT")
+            parts.push(`binary not found: ${REMINDCTL}`);
+        else if (e.code === "EACCES")
+            parts.push(`permission denied: ${REMINDCTL}`);
+        else if (e.stderr?.trim())
+            parts.push(e.stderr.trim());
+        else if (e.message)
+            parts.push(e.message);
+        else
+            parts.push("unknown error");
+        if (e.signal)
+            parts.push(`signal: ${e.signal}`);
+        if (e.exitCode !== undefined && e.exitCode !== null)
+            parts.push(`exit code: ${e.exitCode}`);
+        const error = new Error(`remindctl failed: ${parts.join("; ")}`);
+        error.code = e.code;
+        throw error;
+    }
+}
+function parseJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        console.error(`[remindctl-mcp] Warning: failed to parse JSON output. ` +
+            `Raw (first 200 chars): ${raw.slice(0, 200)}`);
+        return raw.trim();
+    }
+}
+function errorMessage(e) {
+    if (e instanceof Error)
+        return e.message;
+    if (typeof e === "string")
+        return e;
+    return String(e);
+}
+function ok(data) {
+    const text = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+    return { content: [{ type: "text", text }] };
+}
+function fail(msg) {
+    return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+}
+// ---------------------------------------------------------------------------
+// Server setup
+// ---------------------------------------------------------------------------
+const server = new McpServer({
+    name: "remindctl-mcp",
+    version: "1.0.0",
+});
+// ---------------------------------------------------------------------------
+// Tool 1: add_reminder
+// ---------------------------------------------------------------------------
+server.registerTool("add_reminder", {
+    title: "Add Reminder",
+    description: `Add a new reminder to Apple Reminders. Use when the user wants to remember something, create a task, set a to-do, schedule a deadline, or needs to be reminded about anything.
+
+Args:
+  - title (string, required): The reminder text
+  - list (string, optional): Target reminder list (e.g. "Work", "Personal"). Uses default list if omitted.
+  - due (string, optional): Due date in natural language ("tomorrow", "Friday 3pm", "2026-04-05")
+  - notes (string, optional): Additional notes or context
+  - priority (string, optional): none, low, medium, or high`,
+    inputSchema: {
+        title: z.string().min(1).describe("Reminder title/text"),
+        list: z.string().optional().describe("Target reminder list name"),
+        due: z.string().optional().describe("Due date — natural language or ISO date"),
+        notes: z.string().optional().describe("Additional notes"),
+        priority: z.enum(["none", "low", "medium", "high"]).optional().describe("Priority level"),
+    },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+    },
+}, async ({ title, list, due, notes, priority }) => {
+    try {
+        const args = ["add", title];
+        if (list !== undefined)
+            args.push("--list", list);
+        if (due !== undefined)
+            args.push("--due", due);
+        if (notes !== undefined)
+            args.push("--notes", notes);
+        if (priority !== undefined)
+            args.push("--priority", priority);
+        const raw = await runRemindctl(args);
+        return ok(parseJson(raw));
+    }
+    catch (e) {
+        return fail(errorMessage(e));
+    }
+});
+// ---------------------------------------------------------------------------
+// Tool 2: show_reminders
+// ---------------------------------------------------------------------------
+server.registerTool("show_reminders", {
+    title: "Show Reminders",
+    description: `Show reminders from Apple Reminders. Use when the user asks what they need to do, what's on their list, what's due, overdue, or wants to see their agenda/tasks.
+
+Args:
+  - filter (string, optional): today, tomorrow, week, overdue, upcoming, completed, all, or a date string. Defaults to "upcoming".
+  - list (string, optional): Limit to a specific reminder list`,
+    inputSchema: {
+        filter: z
+            .enum(["today", "tomorrow", "week", "overdue", "upcoming", "completed", "all"])
+            .or(z.string())
+            .optional()
+            .default("upcoming")
+            .describe("Filter: today, tomorrow, week, overdue, upcoming, completed, all, or a date"),
+        list: z.string().optional().describe("Limit to a specific reminder list"),
+    },
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+    },
+}, async ({ filter, list }) => {
+    try {
+        const args = ["show"];
+        if (filter !== undefined)
+            args.push(filter);
+        if (list !== undefined)
+            args.push("--list", list);
+        const raw = await runRemindctl(args);
+        return ok(parseJson(raw));
+    }
+    catch (e) {
+        return fail(errorMessage(e));
+    }
+});
+// ---------------------------------------------------------------------------
+// Tool 3: list_reminder_lists
+// ---------------------------------------------------------------------------
+server.registerTool("list_reminder_lists", {
+    title: "List Reminder Lists",
+    description: `List all Apple Reminder lists, or show the contents of a specific list. Use when the user wants to know what lists they have or browse a specific list.
+
+Args:
+  - name (string, optional): If provided, shows reminders in that list. If omitted, lists all available lists.`,
+    inputSchema: {
+        name: z.string().optional().describe("List name — omit to list all lists, provide to show contents"),
+    },
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+    },
+}, async ({ name }) => {
+    try {
+        const args = ["list"];
+        if (name !== undefined)
+            args.push(name);
+        const raw = await runRemindctl(args);
+        return ok(parseJson(raw));
+    }
+    catch (e) {
+        return fail(errorMessage(e));
+    }
+});
+// ---------------------------------------------------------------------------
+// Tool 4: edit_reminder
+// ---------------------------------------------------------------------------
+server.registerTool("edit_reminder", {
+    title: "Edit Reminder",
+    description: `Edit an existing Apple Reminder. Use when the user wants to change a reminder's title, due date, notes, priority, move it to another list, or mark it complete/incomplete.
+
+Args:
+  - id (string, required): Index number or ID prefix from show_reminders output
+  - title (string, optional): New title
+  - list (string, optional): Move to a different list
+  - due (string, optional): New due date
+  - notes (string, optional): New notes
+  - priority (string, optional): none, low, medium, high
+  - clear_due (boolean, optional): Clear the due date
+  - complete (boolean, optional): Mark as completed
+  - incomplete (boolean, optional): Mark as incomplete`,
+    inputSchema: {
+        id: z.string().min(1).describe("Index or ID prefix from show output"),
+        title: z.string().optional().describe("New title"),
+        list: z.string().optional().describe("Move to list"),
+        due: z.string().optional().describe("New due date"),
+        notes: z.string().optional().describe("New notes"),
+        priority: z.enum(["none", "low", "medium", "high"]).optional().describe("Priority level"),
+        clear_due: z.boolean().optional().describe("Clear the due date"),
+        complete: z.boolean().optional().describe("Mark completed"),
+        incomplete: z.boolean().optional().describe("Mark incomplete"),
+    },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    },
+}, async ({ id, title, list, due, notes, priority, clear_due, complete, incomplete }) => {
+    try {
+        const hasEdits = title !== undefined || list !== undefined || due !== undefined ||
+            notes !== undefined || priority !== undefined || clear_due || complete || incomplete;
+        if (!hasEdits) {
+            return fail("No edit fields provided. Specify at least one of: title, list, due, notes, priority, clear_due, complete, incomplete.");
+        }
+        const args = ["edit", id];
+        if (title !== undefined)
+            args.push("--title", title);
+        if (list !== undefined)
+            args.push("--list", list);
+        if (due !== undefined)
+            args.push("--due", due);
+        if (notes !== undefined)
+            args.push("--notes", notes);
+        if (priority !== undefined)
+            args.push("--priority", priority);
+        if (clear_due)
+            args.push("--clear-due");
+        if (complete)
+            args.push("--complete");
+        if (incomplete)
+            args.push("--incomplete");
+        const raw = await runRemindctl(args);
+        return ok(parseJson(raw));
+    }
+    catch (e) {
+        return fail(errorMessage(e));
+    }
+});
+// ---------------------------------------------------------------------------
+// Tool 5: complete_reminders
+// ---------------------------------------------------------------------------
+server.registerTool("complete_reminders", {
+    title: "Complete Reminders",
+    description: `Mark one or more Apple Reminders as complete. Use when the user says they finished a task, did something, or wants to check off a reminder.
+
+Args:
+  - ids (string[], required): Array of index numbers or ID prefixes from show_reminders output`,
+    inputSchema: {
+        ids: z.array(z.string()).min(1).describe("Indexes or ID prefixes to mark complete"),
+    },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    },
+}, async ({ ids }) => {
+    try {
+        const args = ["complete", ...ids];
+        const raw = await runRemindctl(args);
+        return ok(parseJson(raw));
+    }
+    catch (e) {
+        return fail(errorMessage(e));
+    }
+});
+// ---------------------------------------------------------------------------
+// Tool 6: delete_reminders
+// ---------------------------------------------------------------------------
+server.registerTool("delete_reminders", {
+    title: "Delete Reminders",
+    description: `Delete one or more Apple Reminders permanently. Use when the user wants to remove a reminder entirely (not just complete it).
+
+Args:
+  - ids (string[], required): Array of index numbers or ID prefixes from show_reminders output`,
+    inputSchema: {
+        ids: z.array(z.string()).min(1).describe("Indexes or ID prefixes to delete"),
+    },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+    },
+}, async ({ ids }) => {
+    try {
+        const args = ["delete", ...ids, "--force"];
+        const raw = await runRemindctl(args);
+        return ok(parseJson(raw));
+    }
+    catch (e) {
+        return fail(errorMessage(e));
+    }
+});
+// ---------------------------------------------------------------------------
+// Tool 7: manage_reminder_list
+// ---------------------------------------------------------------------------
+server.registerTool("manage_reminder_list", {
+    title: "Manage Reminder List",
+    description: `Create, rename, or delete an Apple Reminder list. Use when the user wants to organize their reminders by creating new lists, renaming existing ones, or removing lists.
+
+Args:
+  - name (string, required): The list name to act on
+  - action (string, required): "create", "rename", or "delete"
+  - new_name (string, optional): Required when action is "rename" — the new name for the list`,
+    inputSchema: {
+        name: z.string().min(1).describe("List name"),
+        action: z.enum(["create", "rename", "delete"]).describe("Action to perform"),
+        new_name: z.string().optional().describe("New name (required for rename)"),
+    },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+    },
+}, async ({ name, action, new_name }) => {
+    try {
+        const args = ["list", name];
+        switch (action) {
+            case "create":
+                args.push("--create");
+                break;
+            case "rename":
+                if (!new_name)
+                    return fail("new_name is required when action is 'rename'");
+                args.push("--rename", new_name);
+                break;
+            case "delete":
+                args.push("--delete", "--force");
+                break;
+        }
+        const raw = await runRemindctl(args);
+        return ok(parseJson(raw));
+    }
+    catch (e) {
+        return fail(errorMessage(e));
+    }
+});
+// ---------------------------------------------------------------------------
+// Startup
+// ---------------------------------------------------------------------------
+async function main() {
+    // Check remindctl is available and authorized
+    try {
+        const raw = await runRemindctl(["status"]);
+        const status = parseJson(raw);
+        if (!status.authorized) {
+            console.error("[remindctl-mcp] remindctl is not authorized to access Reminders. Run: remindctl authorize");
+        }
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT" || e.message?.includes("binary not found")) {
+            console.error("[remindctl-mcp] Could not find remindctl binary. Install: brew install steipete/tap/remindctl");
+            console.error("[remindctl-mcp] Or set REMINDCTL_PATH env var to the binary location.");
+        }
+        else {
+            console.error(`[remindctl-mcp] Health check failed: ${errorMessage(err)}`);
+        }
+        console.error("[remindctl-mcp] Server starting in degraded mode. Tool calls may fail.");
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[remindctl-mcp] Server started (stdio)");
+}
+main().catch((err) => {
+    console.error("[remindctl-mcp] Fatal:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "apple-reminders-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Apple Reminders via remindctl CLI",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "apple-reminders-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && chmod 755 dist/index.js",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.22.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "darwin"
+  ],
+  "license": "MIT"
+}