@mgcrea/mcp-apple-maps
MCP server for the macOS Maps app: the places you have saved.
{
"mcpServers": {
"apple-maps": { "command": "npx", "args": ["-y", "@mgcrea/mcp-apple-maps"] }
}
}
What it reads
Favourites, collections (Guides) and recents, with names, addresses and real coordinates,
from Maps' Core Data store.
| Tool | What |
|---|
apple_maps_list_favorites | the places saved as favourites |
apple_maps_list_collections | the Guides |
apple_maps_list_collection_places | what is filed in one Guide |
apple_maps_list_unfiled_places | saved places filed in no Guide |
apple_maps_list_recents | where you have looked recently |
apple_maps_search_places | all three at once, by name, label or address |
apple_maps_get_place | one place, by ref |
apple_maps_diagnostics | what opened, which columns resolved, what it cannot do |
What it writes
Only with APPLE_MAPS_ALLOW_WRITES=1. Both are unregistered rather than refused when it is off, so a
client that has not opted in is never told they exist.
| Tool | What |
|---|
apple_maps_add_favorite | save a place as a favourite, seeding it through maps:// |
apple_maps_remove_favorite | drop a favourite row |
What it does not do
It reads what is saved on this Mac. It does not search Apple's map of the world, geocode an
address, give directions or compute a travel time. Those are network calls to Apple's services,
not data on your disk.
It writes only favourites, and only with APPLE_MAPS_ALLOW_WRITES set. Everything else here is
read-only. The store is mirrored to iCloud by NSPersistentCloudKitContainer, so a write is an edit
to one replica of a synchronising object graph underneath a running app — a malformed row reaches
every device on the account. That is why a place record is never fabricated: adding a favourite opens
maps:// so that Maps itself mints the record, and only then is it copied. The place is left in
your Recents whether or not you keep the favourite, and resolving it over the network can take tens
of seconds.
Full Disk Access is mandatory
Not an optimisation. Maps ships no scripting dictionary, so there is no Apple Events lane to fall
back to — without the grant this server returns an error, never an empty list. Grant it to the
app running the server, not to Maps.
If a listing comes back empty, that means you have saved nothing of that kind. Run
apple_maps_diagnostics to tell the two apart.
Configuration
| Variable | Default | What |
|---|
APPLE_MAPS_STORE | discovered | explicit store path, for tests and forensic copies |
APPLE_MAPS_INDEX_MODE | auto | auto / ro / immutable / off |
APPLE_MAPS_MAX_RESULTS | 50 | default result ceiling |
APPLE_MAPS_EXPOSE_PROMPTS | on | register the prompt and cupertino://maps/* resources |
APPLE_MAPS_DEBUG | off | verbose logging on stderr |
APPLE_MAPS_ALLOW_WRITES is accepted and ignored: there is no mutating tool for it to gate.
See docs/maps.md for the phase-0 measurements, including the three separate
occasions on which this store was declared not to exist.