macOS Contacts MCP

Instructions

Implementation Reference

• src/index.ts:504-689 (handler)

  The main handler function for the 'update_contact' tool. It retrieves the contact by identifier, then updates specified fields (name, organization, job_title, note, emails, phones, urls) by executing AppleScript commands to modify the macOS Contacts app.
  private async updateContact(args: any): Promise<any> { const { identifier, ...updates } = args; // First get the contact to verify it exists and get the correct ID const existingContact = await this.getContact({ identifier }); if (!existingContact.success) { throw new Error('Contact not found'); } const contactId = existingContact.contact.id; const updatedFields: string[] = []; // Update name if provided if (updates.name !== undefined) { try { // Parse name into first/last name const nameParts = updates.name.trim().split(' '); const firstName = nameParts[0] || ''; const lastName = nameParts.length > 1 ? nameParts.slice(1).join(' ') : ''; const script = `tell application "Contacts" set targetPerson to person id "${contactId}" set first name of targetPerson to "${this.escapeForAppleScript(firstName)}" set last name of targetPerson to "${this.escapeForAppleScript(lastName)}" save end tell`; this.executeAppleScript(script); updatedFields.push('name'); } catch (error) { console.error('Failed to update name:', error); } } // Update basic properties one by one if (updates.organization !== undefined) { try { const script = `tell application "Contacts" set targetPerson to person id "${contactId}" set organization of targetPerson to "${this.escapeForAppleScript(updates.organization)}" save end tell`; this.executeAppleScript(script); updatedFields.push('organization'); } catch (error) { console.error('Failed to update organization:', error); } } if (updates.job_title !== undefined) { try { const script = `tell application "Contacts" set targetPerson to person id "${contactId}" set job title of targetPerson to "${this.escapeForAppleScript(updates.job_title)}" save end tell`; this.executeAppleScript(script); updatedFields.push('job_title'); } catch (error) { console.error('Failed to update job title:', error); } } if (updates.note !== undefined) { try { const script = `tell application "Contacts" set targetPerson to person id "${contactId}" set note of targetPerson to "${this.escapeForAppleScript(updates.note)}" save end tell`; this.executeAppleScript(script); updatedFields.push('note'); } catch (error) { console.error('Failed to update note:', error); } } // Update URLs if provided if (updates.urls !== undefined) { try { // First, remove all existing URLs const clearUrlScript = `tell application "Contacts" set targetPerson to person id "${contactId}" delete every url of targetPerson save end tell`; this.executeAppleScript(clearUrlScript); // Then add new URLs if (updates.urls.length > 0) { let addUrlScript = `tell application "Contacts" set targetPerson to person id "${contactId}"`; updates.urls.forEach((url: any) => { addUrlScript += ` make new url at end of urls of targetPerson with properties {label:"${this.escapeForAppleScript(url.label)}", value:"${this.escapeForAppleScript(url.value)}"}`; }); addUrlScript += ` save end tell`; this.executeAppleScript(addUrlScript); } updatedFields.push('urls'); } catch (error) { console.error('Failed to update URLs:', error); } } // Update emails if provided if (updates.emails !== undefined) { try { // First, remove all existing emails const clearEmailScript = `tell application "Contacts" set targetPerson to person id "${contactId}" delete every email of targetPerson save end tell`; this.executeAppleScript(clearEmailScript); // Then add new emails if (updates.emails.length > 0) { let addEmailScript = `tell application "Contacts" set targetPerson to person id "${contactId}"`; updates.emails.forEach((email: string, index: number) => { const label = index === 0 ? 'home' : index === 1 ? 'work' : `email${index + 1}`; addEmailScript += ` make new email at end of emails of targetPerson with properties {label:"${label}", value:"${this.escapeForAppleScript(email)}"}`; }); addEmailScript += ` save end tell`; this.executeAppleScript(addEmailScript); } updatedFields.push('emails'); } catch (error) { console.error('Failed to update emails:', error); } } // Update phones if provided if (updates.phones !== undefined) { try { // First, remove all existing phones const clearPhoneScript = `tell application "Contacts" set targetPerson to person id "${contactId}" delete every phone of targetPerson save end tell`; this.executeAppleScript(clearPhoneScript); // Then add new phones if (updates.phones.length > 0) { let addPhoneScript = `tell application "Contacts" set targetPerson to person id "${contactId}"`; updates.phones.forEach((phone: string, index: number) => { const label = index === 0 ? 'home' : index === 1 ? 'work' : `phone${index + 1}`; addPhoneScript += ` make new phone at end of phones of targetPerson with properties {label:"${label}", value:"${this.escapeForAppleScript(phone)}"}`; }); addPhoneScript += ` save end tell`; this.executeAppleScript(addPhoneScript); } updatedFields.push('phones'); } catch (error) { console.error('Failed to update phones:', error); } } return { success: true, message: `Updated contact: ${identifier}`, updated_fields: updatedFields, }; }
• src/index.ts:128-179 (schema)

  The input schema definition for the 'update_contact' tool, specifying parameters like identifier (required), name, organization, job_title, emails (array), phones (array), urls (array of objects), and note.
  { name: 'update_contact', description: 'Update an existing contact', inputSchema: { type: 'object', properties: { identifier: { type: 'string', description: 'Contact name or unique ID', }, name: { type: 'string', description: 'Updated full name', }, organization: { type: 'string', description: 'Updated organization or company name', }, job_title: { type: 'string', description: 'Updated job title or position', }, emails: { type: 'array', items: { type: 'string' }, description: 'Updated email addresses (replaces all existing)', }, phones: { type: 'array', items: { type: 'string' }, description: 'Updated phone numbers (replaces all existing)', }, urls: { type: 'array', items: { type: 'object', properties: { label: { type: 'string' }, value: { type: 'string' }, }, required: ['label', 'value'], }, description: 'Updated URLs (replaces all existing)', }, note: { type: 'string', description: 'Updated notes', }, }, required: ['identifier'], }, },
• src/index.ts:225-227 (registration)

  The dispatch case in the CallToolRequest handler that routes 'update_contact' calls to the updateContact method.
  case 'update_contact': result = await this.updateContact(args); break;