Apple MCP

Instructions

Implementation Reference

• tools.ts:259-308 (registration)

  Defines the MAPS_TOOL constant with name, description, inputSchema and adds it to the exported tools array for registration.
  const MAPS_TOOL: Tool = { name: "maps", description: "Search locations, manage guides, save favorites, and get directions using Apple Maps", inputSchema: { type: "object", properties: { operation: { type: "string", description: "Operation to perform with Maps", enum: ["search", "save", "directions", "pin", "listGuides", "addToGuide", "createGuide"] }, query: { type: "string", description: "Search query for locations (required for search)" }, limit: { type: "number", description: "Maximum number of results to return (optional for search)" }, name: { type: "string", description: "Name of the location (required for save and pin)" }, address: { type: "string", description: "Address of the location (required for save, pin, addToGuide)" }, fromAddress: { type: "string", description: "Starting address for directions (required for directions)" }, toAddress: { type: "string", description: "Destination address for directions (required for directions)" }, transportType: { type: "string", description: "Type of transport to use (optional for directions)", enum: ["driving", "walking", "transit"] }, guideName: { type: "string", description: "Name of the guide (required for createGuide and addToGuide)" } }, required: ["operation"] } }; const tools = [CONTACTS_TOOL, NOTES_TOOL, MESSAGES_TOOL, MAIL_TOOL, REMINDERS_TOOL, WEB_SEARCH_TOOL, CALENDAR_TOOL, MAPS_TOOL];
• tools.ts:262-305 (schema)

  Input schema for the 'maps' tool defining parameters for various operations.
  inputSchema: { type: "object", properties: { operation: { type: "string", description: "Operation to perform with Maps", enum: ["search", "save", "directions", "pin", "listGuides", "addToGuide", "createGuide"] }, query: { type: "string", description: "Search query for locations (required for search)" }, limit: { type: "number", description: "Maximum number of results to return (optional for search)" }, name: { type: "string", description: "Name of the location (required for save and pin)" }, address: { type: "string", description: "Address of the location (required for save, pin, addToGuide)" }, fromAddress: { type: "string", description: "Starting address for directions (required for directions)" }, toAddress: { type: "string", description: "Destination address for directions (required for directions)" }, transportType: { type: "string", description: "Type of transport to use (optional for directions)", enum: ["driving", "walking", "transit"] }, guideName: { type: "string", description: "Name of the guide (required for createGuide and addToGuide)" } }, required: ["operation"] }
• utils/maps.ts:83-190 (helper)

  Helper function to search locations in Apple Maps, corresponding to 'search' operation.
  async function searchLocations(query: string, limit: number = 5): Promise<SearchResult> { try { if (!await checkMapsAccess()) { return { success: false, locations: [], message: "Cannot access Maps app. Please grant access in System Settings > Privacy & Security > Automation." }; } console.error(`searchLocations - Searching for: "${query}"`); // First try to use the Maps search function const locations = await run((args: { query: string, limit: number }) => { try { const Maps = Application("Maps"); // Launch Maps and search (this is needed for search to work properly) Maps.activate(); // Execute search using the URL scheme which is more reliable Maps.activate(); const encodedQuery = encodeURIComponent(args.query); Maps.openLocation(`maps://?q=${encodedQuery}`); // For backward compatibility also try the standard search method try { Maps.search(args.query); } catch (e) { // Ignore error if search is not supported } // Wait a bit for search results to populate delay(2); // 2 seconds // Try to get search results, if supported by the version of Maps const locations: MapLocation[] = []; try { // Different versions of Maps have different ways to access results // We'll need to use a different method for each version // Approach 1: Try to get locations directly // (this works on some versions of macOS) const selectedLocation = Maps.selectedLocation(); if (selectedLocation) { // If we have a selected location, use it const location: MapLocation = { id: `loc-${Date.now()}-${Math.random()}`, name: selectedLocation.name() || args.query, address: selectedLocation.formattedAddress() || "Address not available", latitude: selectedLocation.latitude(), longitude: selectedLocation.longitude(), category: selectedLocation.category ? selectedLocation.category() : null, isFavorite: false }; locations.push(location); } else { // If no selected location, use the search field value as name // and try to get coordinates by doing a UI script // Use the user entered search term for the result const location: MapLocation = { id: `loc-${Date.now()}-${Math.random()}`, name: args.query, address: "Search results - address details not available", latitude: null, longitude: null, category: null, isFavorite: false }; locations.push(location); } } catch (e) { // If the above didn't work, at least return something based on the query const location: MapLocation = { id: `loc-${Date.now()}-${Math.random()}`, name: args.query, address: "Search result - address details not available", latitude: null, longitude: null, category: null, isFavorite: false }; locations.push(location); } return locations.slice(0, args.limit); } catch (e) { return []; // Return empty array on any error } }, { query, limit }) as MapLocation[]; return { success: locations.length > 0, locations, message: locations.length > 0 ? `Found ${locations.length} location(s) for "${query}"` : `No locations found for "${query}"` }; } catch (error) { return { success: false, locations: [], message: `Error searching locations: ${error instanceof Error ? error.message : String(error)}` }; } }
• utils/maps.ts:197-279 (helper)

  Helper function to save a location to Maps favorites, for 'save' operation.
  async function saveLocation(name: string, address: string): Promise<SaveResult> { try { if (!await checkMapsAccess()) { return { success: false, message: "Cannot access Maps app. Please grant access in System Settings > Privacy & Security > Automation." }; } console.error(`saveLocation - Saving location: "${name}" at address "${address}"`); const result = await run((args: { name: string, address: string }) => { try { const Maps = Application("Maps"); Maps.activate(); // First search for the location to get its details Maps.search(args.address); // Wait for search to complete delay(2); try { // Try to add to favorites // Different Maps versions have different methods // Try to get the current location const location = Maps.selectedLocation(); if (location) { // Now try to add to favorites // Approach 1: Direct API if available try { Maps.addToFavorites(location, {withProperties: {name: args.name}}); return { success: true, message: `Added "${args.name}" to favorites`, location: { id: `loc-${Date.now()}`, name: args.name, address: location.formattedAddress() || args.address, latitude: location.latitude(), longitude: location.longitude(), category: null, isFavorite: true } }; } catch (e) { // If direct API fails, use UI scripting as fallback // UI scripting would require more complex steps that vary by macOS version return { success: false, message: `Location found but unable to automatically add to favorites. Please manually save "${args.name}" from the Maps app.` }; } } else { return { success: false, message: `Could not find location for "${args.address}"` }; } } catch (e) { return { success: false, message: `Error adding to favorites: ${e}` }; } } catch (e) { return { success: false, message: `Error in Maps: ${e}` }; } }, { name, address }) as SaveResult; return result; } catch (error) { return { success: false, message: `Error saving location: ${error instanceof Error ? error.message : String(error)}` }; } }
• utils/maps.ts:287-348 (helper)

  Helper function to get directions between addresses, for 'directions' operation.
  async function getDirections( fromAddress: string, toAddress: string, transportType: 'driving' | 'walking' | 'transit' = 'driving' ): Promise<DirectionResult> { try { if (!await checkMapsAccess()) { return { success: false, message: "Cannot access Maps app. Please grant access in System Settings > Privacy & Security > Automation." }; } console.error(`getDirections - Getting directions from "${fromAddress}" to "${toAddress}"`); const result = await run((args: { fromAddress: string, toAddress: string, transportType: string }) => { try { const Maps = Application("Maps"); Maps.activate(); // Ask for directions Maps.getDirections({ from: args.fromAddress, to: args.toAddress, by: args.transportType }); // Wait for directions to load delay(2); // There's no direct API to get the route details // We'll return basic success and let the Maps UI show the route return { success: true, message: `Displaying directions from "${args.fromAddress}" to "${args.toAddress}" by ${args.transportType}`, route: { distance: "See Maps app for details", duration: "See Maps app for details", startAddress: args.fromAddress, endAddress: args.toAddress } }; } catch (e) { return { success: false, message: `Error getting directions: ${e}` }; } }, { fromAddress, toAddress, transportType }) as DirectionResult; return result; } catch (error) { return { success: false, message: `Error getting directions: ${error instanceof Error ? error.message : String(error)}` }; } }