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;