Apple MCP

Instructions

Implementation Reference

• tools.ts:3-15 (schema)

  Defines the input schema and metadata for the 'contacts' MCP tool.
  const CONTACTS_TOOL: Tool = { name: "contacts", description: "Search and retrieve contacts from Apple Contacts app", inputSchema: { type: "object", properties: { name: { type: "string", description: "Name to search for (optional - if not provided, returns all contacts). Can be partial name to search." } } } };
• tools.ts:308-310 (registration)

  Registers the CONTACTS_TOOL in the array of tools exported for the MCP server.
  const tools = [CONTACTS_TOOL, NOTES_TOOL, MESSAGES_TOOL, MAIL_TOOL, REMINDERS_TOOL, WEB_SEARCH_TOOL, CALENDAR_TOOL, MAPS_TOOL]; export default tools;
• utils/contacts.ts:4-15 (helper)

  Utility function to check access permissions to the Contacts app before performing operations.
  async function checkContactsAccess(): Promise<boolean> { try { // Try to get the count of contacts as a simple test await runAppleScript(` tell application "Contacts" count every person end tell`); return true; } catch (error) { throw new Error(`Cannot access Contacts app. Please grant access in System Preferences > Security & Privacy > Privacy > Contacts.`); } }
• utils/contacts.ts:17-49 (helper)

  Retrieves all contacts and their associated phone numbers, used when no search name is provided.
  async function getAllNumbers() { try { if (!await checkContactsAccess()) { return {}; } const nums: { [key: string]: string[] } = await run(() => { const Contacts = Application('Contacts'); const people = Contacts.people(); const phoneNumbers: { [key: string]: string[] } = {}; for (const person of people) { try { const name = person.name(); const phones = person.phones().map((phone: any) => phone.value()); if (!phoneNumbers[name]) { phoneNumbers[name] = []; } phoneNumbers[name] = [...phoneNumbers[name], ...phones]; } catch (error) { // Skip contacts that can't be processed } } return phoneNumbers; }); return nums; } catch (error) { throw new Error(`Error accessing contacts: ${error instanceof Error ? error.message : String(error)}`); } }
• utils/contacts.ts:51-77 (helper)

  Searches for a contact by name (partial match) and returns their phone numbers, with fallback search; used when name is provided.
  async function findNumber(name: string) { try { if (!await checkContactsAccess()) { return []; } const nums: string[] = await run((name: string) => { const Contacts = Application('Contacts'); const people = Contacts.people.whose({name: {_contains: name}}); const phones = people.length > 0 ? people[0].phones() : []; return phones.map((phone: any) => phone.value()); }, name); // If no numbers found, run getNumbers() to find the closest match if (nums.length === 0) { const allNumbers = await getAllNumbers(); const closestMatch = Object.keys(allNumbers).find(personName => personName.toLowerCase().includes(name.toLowerCase()) ); return closestMatch ? allNumbers[closestMatch] : []; } return nums; } catch (error) { throw new Error(`Error finding contact: ${error instanceof Error ? error.message : String(error)}`); } }