macOS Contacts MCP

Instructions

Implementation Reference

• src/index.ts:691-734 (handler)

  The main handler function that implements the get_recent_contacts tool by executing AppleScript to fetch recent contacts from macOS Contacts app.

    private async getRecentContacts(args: any): Promise<any> {
      const { days_back = 30, type = 'modified', limit = 20 } = args;
  
      // Use a unique delimiter that won't conflict with dates
      const script = `tell application "Contacts"
    set contactList to {}
    set allPeople to people
    repeat with i from 1 to ${Math.min(limit, 20)}
      if i > (count of allPeople) then exit repeat
      set aPerson to item i of allPeople
      set end of contactList to (name of aPerson & "###SPLIT###" & modification date of aPerson & "###END###")
    end repeat
    return contactList
  end tell`;
  
      try {
        const result = this.executeAppleScript(script);
        if (!result) {
          return { success: true, type, days_back, count: 0, contacts: [] };
        }
        
        // Split by ###END### to separate entries
        const entries = result.split('###END###').filter(entry => entry.trim());
        
        const contacts = entries.map(entry => {
          const cleanEntry = entry.replace(/^, /, ''); // Remove leading comma
          const parts = cleanEntry.split('###SPLIT###');
          return {
            name: parts[0] || '',
            modification_date: parts[1] || '',
          };
        }).slice(0, limit);
        
        return {
          success: true,
          type,
          days_back,
          count: contacts.length,
          contacts,
        };
      } catch (error) {
        throw new Error(`Get recent contacts failed: ${error}`);
      }
    }

• src/index.ts:183-202 (schema)

  Input schema defining parameters for the get_recent_contacts tool: days_back, type (created/modified/both), and limit.

  inputSchema: {
    type: 'object',
    properties: {
      days_back: {
        type: 'integer',
        description: 'Number of days back to search',
        default: 30,
      },
      type: {
        type: 'string',
        enum: ['created', 'modified', 'both'],
        description: 'Type of date to filter by',
        default: 'modified',
      },
      limit: {
        type: 'integer',
        description: 'Maximum number of results to return',
        default: 20,
      },
    },

• src/index.ts:180-204 (registration)

  Tool registration entry in the ListToolsRequestSchema response, including name, description, and input schema.

  {
    name: 'get_recent_contacts',
    description: 'Get contacts created or modified within a date range',
    inputSchema: {
      type: 'object',
      properties: {
        days_back: {
          type: 'integer',
          description: 'Number of days back to search',
          default: 30,
        },
        type: {
          type: 'string',
          enum: ['created', 'modified', 'both'],
          description: 'Type of date to filter by',
          default: 'modified',
        },
        limit: {
          type: 'integer',
          description: 'Maximum number of results to return',
          default: 20,
        },
      },
    },
  },

• src/index.ts:228-230 (registration)

  Dispatch case in the CallToolRequestSchema handler that routes calls to the getRecentContacts handler function.

  case 'get_recent_contacts':
    result = await this.getRecentContacts(args);
    break;