maps
Search locations, get directions, save favorites, and manage guides using Apple Maps data through the MCP server.
Instructions
Search locations, manage guides, save favorites, and get directions using Apple Maps
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | Operation to perform with Maps | |
| query | No | Search query for locations (required for search) | |
| limit | No | Maximum number of results to return (optional for search) | |
| name | No | Name of the location (required for save and pin) | |
| address | No | Address of the location (required for save, pin, addToGuide) | |
| fromAddress | No | Starting address for directions (required for directions) | |
| toAddress | No | Destination address for directions (required for directions) | |
| transportType | No | Type of transport to use (optional for directions) | |
| guideName | No | Name of the guide (required for createGuide and addToGuide) |
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)}` }; } }