@aernoud/contactsmcp 0.1.1

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { searchContacts } from "./tools/searchContacts.js";
+import { readContact } from "./tools/readContact.js";
+import { createContact } from "./tools/createContact.js";
+import { updateContact } from "./tools/updateContact.js";
+import { listGroups } from "./tools/listGroups.js";
+import { addToGroup } from "./tools/addToGroup.js";
+const server = new McpServer({
+    name: "contactsmcp",
+    version: "0.1.0",
+});
+server.tool("search-contacts", "Search contacts in macOS Contacts.app by name, email, or phone number", {
+    query: z.string().describe("Search query — matches against name, email, and phone"),
+    limit: z.number().optional().default(25).describe("Max results to return"),
+}, async ({ query, limit }) => {
+    const contacts = await searchContacts(query, limit);
+    return { content: [{ type: "text", text: JSON.stringify(contacts, null, 2) }] };
+});
+server.tool("read-contact", "Get full details of a contact by their Contacts.app ID", {
+    contactId: z.string().describe("Contact ID from Contacts.app (from search results)"),
+}, async ({ contactId }) => {
+    const contact = await readContact(contactId);
+    if (!contact) {
+        return { content: [{ type: "text", text: "Contact not found." }] };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(contact, null, 2) }] };
+});
+server.tool("create-contact", "Create a new contact in macOS Contacts.app", {
+    firstName: z.string().describe("First name"),
+    lastName: z.string().describe("Last name"),
+    email: z.string().optional().describe("Email address"),
+    phone: z.string().optional().describe("Phone number"),
+    organization: z.string().optional().describe("Organization / company name"),
+}, async ({ firstName, lastName, email, phone, organization }) => {
+    const result = await createContact(firstName, lastName, email, phone, organization);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("update-contact", "Update fields on an existing contact in macOS Contacts.app", {
+    contactId: z.string().describe("Contact ID from Contacts.app"),
+    firstName: z.string().optional().describe("New first name"),
+    lastName: z.string().optional().describe("New last name"),
+    email: z.string().optional().describe("New primary email address"),
+    phone: z.string().optional().describe("New primary phone number"),
+    organization: z.string().optional().describe("New organization / company name"),
+}, async ({ contactId, firstName, lastName, email, phone, organization }) => {
+    const result = await updateContact(contactId, firstName, lastName, email, phone, organization);
+    if (!result) {
+        return { content: [{ type: "text", text: "Contact not found." }] };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("list-groups", "List all contact groups in macOS Contacts.app with member counts", {}, async () => {
+    const groups = await listGroups();
+    return { content: [{ type: "text", text: JSON.stringify(groups, null, 2) }] };
+});
+server.tool("add-to-group", "Add a contact to a group in macOS Contacts.app", {
+    contactId: z.string().describe("Contact ID from Contacts.app"),
+    groupName: z.string().describe("Name of the group to add the contact to"),
+}, async ({ contactId, groupName }) => {
+    const result = await addToGroup(contactId, groupName);
+    if (!result) {
+        return { content: [{ type: "text", text: "Contact not found." }] };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools/addToGroup.d.ts

@@ -0,0 +1,5 @@
+export declare function addToGroup(contactId: string, groupName: string): Promise<{
+    contactId: string;
+    groupName: string;
+    status: string;
+} | null>;

package/dist/tools/addToGroup.js

@@ -0,0 +1,30 @@
+import { runAppleScript, escapeForAppleScript } from "@mailappmcp/shared";
+export async function addToGroup(contactId, groupName) {
+    const cId = escapeForAppleScript(contactId);
+    const gName = escapeForAppleScript(groupName);
+    const script = `
+tell application "Contacts"
+  set personResults to (every person whose id is "${cId}")
+  if (count of personResults) = 0 then
+    return "CONTACT_NOT_FOUND"
+  end if
+  set groupResults to (every group whose name is "${gName}")
+  if (count of groupResults) = 0 then
+    return "GROUP_NOT_FOUND"
+  end if
+  set p to item 1 of personResults
+  set g to item 1 of groupResults
+  add p to g
+  save
+  return "done"
+end tell`;
+    const result = await runAppleScript(script);
+    const trimmed = result.trim();
+    if (trimmed === "CONTACT_NOT_FOUND") {
+        return null;
+    }
+    if (trimmed === "GROUP_NOT_FOUND") {
+        throw new Error(`Group not found: ${groupName}`);
+    }
+    return { contactId, groupName, status: "added" };
+}

package/dist/tools/createContact.d.ts

@@ -0,0 +1,8 @@
+export declare function createContact(firstName: string, lastName: string, email?: string, phone?: string, organization?: string): Promise<{
+    id: string;
+    firstName: string;
+    lastName: string;
+    email: string | undefined;
+    phone: string | undefined;
+    organization: string | undefined;
+}>;

package/dist/tools/createContact.js

@@ -0,0 +1,25 @@
+import { runAppleScript, escapeForAppleScript } from "@mailappmcp/shared";
+export async function createContact(firstName, lastName, email, phone, organization) {
+    const fName = escapeForAppleScript(firstName);
+    const lName = escapeForAppleScript(lastName);
+    const emailBlock = email
+        ? `make new email at end of emails of newPerson with properties {label:"work", value:"${escapeForAppleScript(email)}"}`
+        : "";
+    const phoneBlock = phone
+        ? `make new phone at end of phones of newPerson with properties {label:"mobile", value:"${escapeForAppleScript(phone)}"}`
+        : "";
+    const orgBlock = organization
+        ? `set organization of newPerson to "${escapeForAppleScript(organization)}"`
+        : "";
+    const script = `
+tell application "Contacts"
+  set newPerson to make new person with properties {first name:"${fName}", last name:"${lName}"}
+  ${emailBlock}
+  ${phoneBlock}
+  ${orgBlock}
+  save
+  return id of newPerson
+end tell`;
+    const id = await runAppleScript(script);
+    return { id: id.trim(), firstName, lastName, email, phone, organization };
+}

package/dist/tools/listGroups.d.ts

@@ -0,0 +1,3 @@
+export declare function listGroups(): Promise<{
+    memberCount: number;
+}[]>;

package/dist/tools/listGroups.js

@@ -0,0 +1,18 @@
+import { runAppleScript, parseRecords, FIELD_SEP, RECORD_SEP } from "@mailappmcp/shared";
+export async function listGroups() {
+    const script = `
+tell application "Contacts"
+  set output to ""
+  repeat with g in every group
+    set gCount to 0
+    try
+      set gCount to count of people of g
+    end try
+    set output to output & (id of g) & "${FIELD_SEP}" & (name of g) & "${FIELD_SEP}" & gCount & "${RECORD_SEP}"
+  end repeat
+  return output
+end tell`;
+    const raw = await runAppleScript(script);
+    const records = parseRecords(raw, ["id", "name", "memberCount"]);
+    return records.map((r) => ({ ...r, memberCount: parseInt(r.memberCount, 10) || 0 }));
+}

package/dist/tools/readContact.d.ts

@@ -0,0 +1,19 @@
+export declare function readContact(contactId: string): Promise<{
+    name: string;
+    firstName: string;
+    lastName: string;
+    organization: string;
+    emails: {
+        label: string;
+        value: string;
+    }[];
+    phones: {
+        label: string;
+        value: string;
+    }[];
+    addresses: {
+        label: string;
+        value: string;
+    }[];
+    note: string;
+} | null>;

package/dist/tools/readContact.js

@@ -0,0 +1,80 @@
+import { runAppleScript, escapeForAppleScript, FIELD_SEP } from "@mailappmcp/shared";
+export async function readContact(contactId) {
+    const cId = escapeForAppleScript(contactId);
+    const script = `
+tell application "Contacts"
+  set results to (every person whose id is "${cId}")
+  if (count of results) = 0 then
+    return "NOT_FOUND"
+  end if
+  set p to item 1 of results
+  set pName to ""
+  try
+    set pName to name of p
+  end try
+  set pFirst to ""
+  try
+    set pFirst to first name of p as string
+    if pFirst is "missing value" then set pFirst to ""
+  end try
+  set pLast to ""
+  try
+    set pLast to last name of p as string
+    if pLast is "missing value" then set pLast to ""
+  end try
+  set pOrg to ""
+  try
+    set pOrg to organization of p as string
+    if pOrg is "missing value" then set pOrg to ""
+  end try
+  set emailList to ""
+  try
+    repeat with e in emails of p
+      set emailList to emailList & (label of e) & ":" & (value of e) & ","
+    end repeat
+  end try
+  set phoneList to ""
+  try
+    repeat with ph in phones of p
+      set phoneList to phoneList & (label of ph) & ":" & (value of ph) & ","
+    end repeat
+  end try
+  set addrList to ""
+  try
+    repeat with a in addresses of p
+      set addrList to addrList & (label of a) & ":" & (formatted address of a) & ","
+    end repeat
+  end try
+  set pNote to ""
+  try
+    set pNote to note of p as string
+    if pNote is "missing value" then set pNote to ""
+  end try
+  return pName & "${FIELD_SEP}" & pFirst & "${FIELD_SEP}" & pLast & "${FIELD_SEP}" & pOrg & "${FIELD_SEP}" & emailList & "${FIELD_SEP}" & phoneList & "${FIELD_SEP}" & addrList & "${FIELD_SEP}" & pNote
+end tell`;
+    const raw = await runAppleScript(script);
+    if (raw.trim() === "NOT_FOUND") {
+        return null;
+    }
+    const parts = raw.split(FIELD_SEP);
+    const parseList = (s) => (s ?? "")
+        .trim()
+        .split(",")
+        .filter(Boolean)
+        .map((item) => {
+        const colonIdx = item.indexOf(":");
+        if (colonIdx === -1)
+            return { label: "", value: item };
+        return { label: item.slice(0, colonIdx), value: item.slice(colonIdx + 1) };
+    });
+    return {
+        name: (parts[0] ?? "").trim(),
+        firstName: (parts[1] ?? "").trim(),
+        lastName: (parts[2] ?? "").trim(),
+        organization: (parts[3] ?? "").trim(),
+        emails: parseList(parts[4] ?? ""),
+        phones: parseList(parts[5] ?? ""),
+        addresses: parseList(parts[6] ?? ""),
+        note: (parts[7] ?? "").trim(),
+    };
+}

package/dist/tools/searchContacts.d.ts

@@ -0,0 +1 @@
+export declare function searchContacts(query: string, limit?: number): Promise<Record<string, string>[]>;

package/dist/tools/searchContacts.js

@@ -0,0 +1,69 @@
+import { runAppleScript, escapeForAppleScript, parseRecords, FIELD_SEP, RECORD_SEP } from "@mailappmcp/shared";
+export async function searchContacts(query, limit = 25) {
+    const q = escapeForAppleScript(query);
+    const script = `
+tell application "Contacts"
+  set matchedPeople to {}
+  try
+    set nameMatches to (every person whose name contains "${q}")
+    repeat with p in nameMatches
+      set end of matchedPeople to p
+    end repeat
+  end try
+  if (count of matchedPeople) = 0 then
+    try
+      set allPeople to every person
+      repeat with p in allPeople
+        set found to false
+        repeat with e in emails of p
+          if value of e contains "${q}" then
+            set found to true
+            exit repeat
+          end if
+        end repeat
+        if not found then
+          repeat with ph in phones of p
+            if value of ph contains "${q}" then
+              set found to true
+              exit repeat
+            end if
+          end repeat
+        end if
+        if found then
+          set end of matchedPeople to p
+        end if
+      end repeat
+    end try
+  end if
+  set output to ""
+  set maxCount to ${limit}
+  set i to 0
+  repeat with p in matchedPeople
+    if i >= maxCount then exit repeat
+    set pId to id of p
+    set pName to name of p
+    set pOrg to ""
+    try
+      set pOrg to organization of p as string
+    end try
+    if pOrg is "missing value" then set pOrg to ""
+    set pEmail to ""
+    try
+      if (count of emails of p) > 0 then
+        set pEmail to value of first email of p
+      end if
+    end try
+    set pPhone to ""
+    try
+      if (count of phones of p) > 0 then
+        set pPhone to value of first phone of p
+      end if
+    end try
+    set output to output & pId & "${FIELD_SEP}" & pName & "${FIELD_SEP}" & pOrg & "${FIELD_SEP}" & pEmail & "${FIELD_SEP}" & pPhone & "${RECORD_SEP}"
+    set i to i + 1
+  end repeat
+  return output
+end tell`;
+    const raw = await runAppleScript(script);
+    return parseRecords(raw, ["id", "name", "organization", "email", "phone"]);
+}

package/dist/tools/updateContact.d.ts

@@ -0,0 +1,10 @@
+export declare function updateContact(contactId: string, firstName?: string, lastName?: string, email?: string, phone?: string, organization?: string): Promise<{
+    contactId: string;
+    updated: {
+        firstName: string | undefined;
+        lastName: string | undefined;
+        email: string | undefined;
+        phone: string | undefined;
+        organization: string | undefined;
+    };
+} | null>;

package/dist/tools/updateContact.js

@@ -0,0 +1,49 @@
+import { runAppleScript, escapeForAppleScript } from "@mailappmcp/shared";
+export async function updateContact(contactId, firstName, lastName, email, phone, organization) {
+    const cId = escapeForAppleScript(contactId);
+    const firstNameBlock = firstName !== undefined
+        ? `set first name of p to "${escapeForAppleScript(firstName)}"`
+        : "";
+    const lastNameBlock = lastName !== undefined
+        ? `set last name of p to "${escapeForAppleScript(lastName)}"`
+        : "";
+    const orgBlock = organization !== undefined
+        ? `set organization of p to "${escapeForAppleScript(organization)}"`
+        : "";
+    const emailBlock = email !== undefined
+        ? `
+  if (count of emails of p) > 0 then
+    set value of first email of p to "${escapeForAppleScript(email)}"
+  else
+    make new email at end of emails of p with properties {label:"work", value:"${escapeForAppleScript(email)}"}
+  end if`
+        : "";
+    const phoneBlock = phone !== undefined
+        ? `
+  if (count of phones of p) > 0 then
+    set value of first phone of p to "${escapeForAppleScript(phone)}"
+  else
+    make new phone at end of phones of p with properties {label:"mobile", value:"${escapeForAppleScript(phone)}"}
+  end if`
+        : "";
+    const script = `
+tell application "Contacts"
+  set results to (every person whose id is "${cId}")
+  if (count of results) = 0 then
+    return "NOT_FOUND"
+  end if
+  set p to item 1 of results
+  ${firstNameBlock}
+  ${lastNameBlock}
+  ${orgBlock}
+  ${emailBlock}
+  ${phoneBlock}
+  save
+  return "ok"
+end tell`;
+    const result = await runAppleScript(script);
+    if (result.trim() === "NOT_FOUND") {
+        return null;
+    }
+    return { contactId, updated: { firstName, lastName, email, phone, organization } };
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@aernoud/contactsmcp",
+  "version": "0.1.1",
+  "description": "MCP server for macOS Contacts.app — contact management via AppleScript",
+  "mcpName": "io.github.aernouddekker/contactsmcp",
+  "type": "module",
+  "bin": { "contactsmcp": "./dist/index.js" },
+  "files": ["dist"],
+  "scripts": { "build": "tsc", "start": "node dist/index.js", "prepublishOnly": "npm run build" },
+  "keywords": ["mcp", "mcp-server", "contacts", "address-book", "macos", "applescript", "claude"],
+  "author": "Aernoud Dekker",
+  "repository": { "type": "git", "url": "https://github.com/aernouddekker/macos-mcp.git", "directory": "packages/contacts" },
+  "dependencies": { "@mailappmcp/shared": "*", "@modelcontextprotocol/sdk": "^1.12.0", "zod": "^3.23.0" },
+  "devDependencies": { "typescript": "^5.5.0", "@types/node": "^22.0.0" },
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "os": ["darwin"]
+}