macOS Contacts MCP

Instructions

Implementation Reference

• src/index.ts:334-426 (handler)

  The core handler function for the 'get_contact' tool. It uses AppleScript to query the macOS Contacts application for a contact by ID or name, fetches basic info first, then retrieves emails, phones, and URLs separately, and returns a structured contact object.
  private async getContact(args: any): Promise<any> { const { identifier } = args; // Simple approach - get basic info first, then build up let script = `tell application "Contacts" try set targetPerson to person id "${identifier}" on error try set targetPerson to person "${identifier}" on error return "Contact not found" end try end try return id of targetPerson & "|" & name of targetPerson & "|" & organization of targetPerson & "|" & job title of targetPerson & "|" & note of targetPerson end tell`; try { const result = this.executeAppleScript(script); if (result === 'Contact not found') { return { success: false, message: 'Contact not found' }; } const parts = result.split('|'); const contact: any = { id: parts[0] || '', name: parts[1] || '', organization: parts[2] || '', job_title: parts[3] || '', note: parts[4] || '', }; // Get emails separately try { const emailScript = `tell application "Contacts" set targetPerson to person id "${contact.id}" set emailList to {} repeat with anEmail in emails of targetPerson set end of emailList to value of anEmail end repeat return emailList end tell`; const emailResult = this.executeAppleScript(emailScript); contact.emails = emailResult ? emailResult.split(', ') : []; } catch { contact.emails = []; } // Get phones separately try { const phoneScript = `tell application "Contacts" set targetPerson to person id "${contact.id}" set phoneList to {} repeat with aPhone in phones of targetPerson set end of phoneList to value of aPhone end repeat return phoneList end tell`; const phoneResult = this.executeAppleScript(phoneScript); contact.phones = phoneResult ? phoneResult.split(', ') : []; } catch { contact.phones = []; } // Get URLs separately try { const urlScript = `tell application "Contacts" set targetPerson to person id "${contact.id}" set urlList to {} repeat with aUrl in urls of targetPerson set end of urlList to (label of aUrl & ":" & value of aUrl) end repeat return urlList end tell`; const urlResult = this.executeAppleScript(urlScript); if (urlResult) { contact.urls = urlResult.split(', ').map(item => { const [label, ...valueParts] = item.split(':'); return { label: label || '', value: valueParts.join(':') || '' }; }); } else { contact.urls = []; } } catch { contact.urls = []; } return { success: true, contact }; } catch (error) { throw new Error(`Get contact failed: ${error}`); } }
• src/index.ts:66-79 (schema)

  Tool registration entry defining the name, description, and input schema for 'get_contact', which requires an 'identifier' string (contact name or ID).
  { name: 'get_contact', description: 'Get full contact details by name or ID', inputSchema: { type: 'object', properties: { identifier: { type: 'string', description: 'Contact name or unique ID', }, }, required: ['identifier'], }, },
• src/index.ts:219-221 (registration)

  Dispatches the 'get_contact' tool call to the handler function within the CallToolRequestHandler switch statement.
  case 'get_contact': result = await this.getContact(args); break;