apple-maps-mcp 1.0.0__tar.gz

apple_maps_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apple MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apple_maps_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: apple-maps-mcp
+Version: 1.0.0
+Summary: Local Apple Maps MCP server for macOS
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JonathanRReed/Apple-MCPs
+Project-URL: Repository, https://github.com/JonathanRReed/Apple-MCPs
+Project-URL: Changelog, https://github.com/JonathanRReed/Apple-MCPs/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/JonathanRReed/Apple-MCPs/issues
+Keywords: mcp,model-context-protocol,macos,apple,ai-agent,automation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: apple-mcp-common<2,>=1.0.0
+Requires-Dist: mcp<3,>=2.0.0
+Requires-Dist: pydantic>=2.12.0
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: ruff<1,>=0.12; extra == "dev"
+Dynamic: license-file
+
+<!-- mcp-name: io.github.jonathanrreed/apple-maps-mcp -->
+
+# Apple Maps MCP
+
+Local MCP server for Apple Maps search and routing on macOS.
+
+## Capabilities
+
+- search for places
+- estimate route distance and travel time
+- build Apple Maps links
+- open directions in Apple Maps
+- resource: `maps://status`
+- prompt: `maps_plan_route`
+- tool discovery helpers `search_tools` and `get_tool_info` for context-constrained clients
+
+## Install On This Mac
+
+<details>
+<summary>Quick start (uvx, from PyPI)</summary>
+
+With [uv](https://docs.astral.sh/uv/getting-started/installation/) installed:
+
+```bash
+uvx apple-maps-mcp
+```
+
+No clone, no venv management.
+
+</details>
+
+<details>
+<summary>From a clone</summary>
+
+```bash
+git clone https://github.com/JonathanRReed/Apple-MCPs.git
+cd Apple-MCPs
+uv sync --all-packages
+```
+
+This builds one workspace environment with every server's entry point in `.venv/bin` (for example `.venv/bin/apple-maps-mcp`). You can also point an MCP client at `AppleMaps-MCP/start.sh`, which prefers `uv run` and falls back to a plain venv bootstrap (Python 3.11+ required).
+
+</details>
+
+## Install In AI Agents
+
+```json
+{
+  "mcpServers": {
+    "apple-maps": {
+      "command": "uvx",
+      "args": ["apple-maps-mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+Running from a clone instead? Use `/path/to/Apple-MCPs/AppleMaps-MCP/start.sh` as the command with empty `args`.
+
+Claude Code:
+
+```bash
+claude mcp add --transport stdio --scope project apple-maps -- uvx apple-maps-mcp
+```
+
+## Transport
+
+`stdio` is the default and recommended transport. Set `APPLE_MAPS_MCP_TRANSPORT=streamable-http` (with optional `APPLE_MAPS_MCP_HOST` and `APPLE_MAPS_MCP_PORT`) to serve Streamable HTTP instead.
+
+## Prompting Notes
+
+- `tools/list` returns the full Maps tool surface. Context-constrained clients can use `search_tools` first, then `get_tool_info` for the Maps tool they need.
+- Use this server when travel, routing, or place lookup affects a Calendar, Reminders, Messages, or Mail action.
+- Confirm origin, destination, and transport mode before writing a time-sensitive plan.
+- If helper compilation fails, install Xcode command line tools and retry.
+
+## Health And Recovery
+
+- `maps_health`
+- `maps_permission_guide`
+
+## Launch Checklist
+
+- Add `uvx apple-maps-mcp` (or a clone's `AppleMaps-MCP/start.sh`) to your MCP client
+- Reload or reconnect the client so the Maps tool surface is loaded into context
+- Call `maps_health` first
+- If the local helper or routing surface is blocked, call `maps_permission_guide`
+- Run `maps_search_places` once to confirm the local Swift helper compiles

apple_maps_mcp-1.0.0/README.md

@@ -0,0 +1,89 @@
+<!-- mcp-name: io.github.jonathanrreed/apple-maps-mcp -->
+
+# Apple Maps MCP
+
+Local MCP server for Apple Maps search and routing on macOS.
+
+## Capabilities
+
+- search for places
+- estimate route distance and travel time
+- build Apple Maps links
+- open directions in Apple Maps
+- resource: `maps://status`
+- prompt: `maps_plan_route`
+- tool discovery helpers `search_tools` and `get_tool_info` for context-constrained clients
+
+## Install On This Mac
+
+<details>
+<summary>Quick start (uvx, from PyPI)</summary>
+
+With [uv](https://docs.astral.sh/uv/getting-started/installation/) installed:
+
+```bash
+uvx apple-maps-mcp
+```
+
+No clone, no venv management.
+
+</details>
+
+<details>
+<summary>From a clone</summary>
+
+```bash
+git clone https://github.com/JonathanRReed/Apple-MCPs.git
+cd Apple-MCPs
+uv sync --all-packages
+```
+
+This builds one workspace environment with every server's entry point in `.venv/bin` (for example `.venv/bin/apple-maps-mcp`). You can also point an MCP client at `AppleMaps-MCP/start.sh`, which prefers `uv run` and falls back to a plain venv bootstrap (Python 3.11+ required).
+
+</details>
+
+## Install In AI Agents
+
+```json
+{
+  "mcpServers": {
+    "apple-maps": {
+      "command": "uvx",
+      "args": ["apple-maps-mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+Running from a clone instead? Use `/path/to/Apple-MCPs/AppleMaps-MCP/start.sh` as the command with empty `args`.
+
+Claude Code:
+
+```bash
+claude mcp add --transport stdio --scope project apple-maps -- uvx apple-maps-mcp
+```
+
+## Transport
+
+`stdio` is the default and recommended transport. Set `APPLE_MAPS_MCP_TRANSPORT=streamable-http` (with optional `APPLE_MAPS_MCP_HOST` and `APPLE_MAPS_MCP_PORT`) to serve Streamable HTTP instead.
+
+## Prompting Notes
+
+- `tools/list` returns the full Maps tool surface. Context-constrained clients can use `search_tools` first, then `get_tool_info` for the Maps tool they need.
+- Use this server when travel, routing, or place lookup affects a Calendar, Reminders, Messages, or Mail action.
+- Confirm origin, destination, and transport mode before writing a time-sensitive plan.
+- If helper compilation fails, install Xcode command line tools and retry.
+
+## Health And Recovery
+
+- `maps_health`
+- `maps_permission_guide`
+
+## Launch Checklist
+
+- Add `uvx apple-maps-mcp` (or a clone's `AppleMaps-MCP/start.sh`) to your MCP client
+- Reload or reconnect the client so the Maps tool surface is loaded into context
+- Call `maps_health` first
+- If the local helper or routing surface is blocked, call `maps_permission_guide`
+- Run `maps_search_places` once to confirm the local Swift helper compiles

apple_maps_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "apple-maps-mcp"
+version = "1.0.0"
+description = "Local Apple Maps MCP server for macOS"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = ["mcp", "model-context-protocol", "macos", "apple", "ai-agent", "automation"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: MacOS X",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "apple-mcp-common>=1.0.0,<2",
+  "mcp>=2.0.0,<3",
+  "pydantic>=2.12.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/JonathanRReed/Apple-MCPs"
+Repository = "https://github.com/JonathanRReed/Apple-MCPs"
+Changelog = "https://github.com/JonathanRReed/Apple-MCPs/blob/main/CHANGELOG.md"
+Issues = "https://github.com/JonathanRReed/Apple-MCPs/issues"
+
+[project.scripts]
+apple-maps-mcp = "apple_maps_mcp.tools:main"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8,<10",
+  "ruff>=0.12,<1",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.package-data]
+apple_maps_mcp = ["*.swift"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.uv.sources]
+apple-mcp-common = { workspace = true }

apple_maps_mcp-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

apple_maps_mcp-1.0.0/src/apple_maps_mcp/__init__.py

@@ -0,0 +1 @@
+"""Apple Maps MCP package."""

apple_maps_mcp-1.0.0/src/apple_maps_mcp/apple_maps_bridge.swift

@@ -0,0 +1,234 @@
+import Foundation
+import MapKit
+
+struct BridgeFailure: Error {
+    let errorCode: String
+    let message: String
+    let suggestion: String?
+}
+
+struct ErrorPayload: Encodable {
+    let ok = false
+    let error_code: String
+    let message: String
+    let suggestion: String?
+}
+
+struct PlaceRecord: Encodable {
+    let name: String
+    let address: String?
+    let latitude: Double?
+    let longitude: Double?
+    let phone: String?
+    let url: String?
+}
+
+struct PlaceListPayload: Encodable {
+    let places: [PlaceRecord]
+}
+
+struct DirectionsPayload: Encodable {
+    let origin: PlaceRecord
+    let destination: PlaceRecord
+    let transport: String
+    let distance_meters: Double
+    let expected_travel_time_seconds: Double
+    let advisory_notices: [String]
+}
+
+@main
+struct AppleMapsBridge {
+    static let asyncTimeoutSeconds: TimeInterval = 15
+    static let encoder: JSONEncoder = {
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.sortedKeys]
+        return encoder
+    }()
+
+    static func main() async {
+        do {
+            let arguments = Array(CommandLine.arguments.dropFirst())
+            guard arguments.count == 2 else {
+                throw BridgeFailure(errorCode: "USAGE_ERROR", message: "Expected a command and a JSON payload.", suggestion: "Pass search-places or directions with a JSON object.")
+            }
+            let command = arguments[0]
+            let payload = try decodeJSONObject(arguments[1])
+            let data = try await handle(command: command, payload: payload)
+            FileHandle.standardOutput.write(data)
+        } catch let failure as BridgeFailure {
+            writeErrorAndExit(failure)
+        } catch {
+            writeErrorAndExit(BridgeFailure(errorCode: "UNEXPECTED_ERROR", message: String(describing: error), suggestion: "Retry the Apple Maps request."))
+        }
+    }
+
+    static func handle(command: String, payload: [String: Any]) async throws -> Data {
+        switch command {
+        case "search-places":
+            let query = try string(payload["query"], field: "query")
+            let limit = try int(payload["limit"], field: "limit", defaultValue: 5)
+            let places = try await searchPlaces(query: query, limit: limit)
+            return try encoder.encode(PlaceListPayload(places: places))
+        case "directions":
+            let originQuery = try string(payload["origin"], field: "origin")
+            let destinationQuery = try string(payload["destination"], field: "destination")
+            let transport = try string(payload["transport"], field: "transport")
+            let route = try await directions(originQuery: originQuery, destinationQuery: destinationQuery, transport: transport)
+            return try encoder.encode(route)
+        default:
+            throw BridgeFailure(errorCode: "UNKNOWN_COMMAND", message: "Unknown command '\(command)'.", suggestion: "Use search-places or directions.")
+        }
+    }
+
+    static func searchPlaces(query: String, limit: Int) async throws -> [PlaceRecord] {
+        let request = MKLocalSearch.Request()
+        request.naturalLanguageQuery = query
+        let search = MKLocalSearch(request: request)
+        let response = try await withTimeout(
+            errorCode: "SEARCH_TIMEOUT",
+            message: "Apple Maps search timed out.",
+            suggestion: "Retry the query, or confirm Maps services are available on this Mac."
+        ) {
+            try await search.start()
+        }
+        let items = response.mapItems.prefix(limit)
+        return items.map(placeRecord)
+    }
+
+    static func directions(originQuery: String, destinationQuery: String, transport: String) async throws -> DirectionsPayload {
+        let originItem = try await resolveFirstMapItem(query: originQuery)
+        let destinationItem = try await resolveFirstMapItem(query: destinationQuery)
+
+        let request = MKDirections.Request()
+        request.source = originItem
+        request.destination = destinationItem
+        request.transportType = transportType(transport)
+
+        let directions = MKDirections(request: request)
+        let routeResponse = try await withTimeout(
+            errorCode: "DIRECTIONS_TIMEOUT",
+            message: "Apple Maps directions timed out.",
+            suggestion: "Retry the request, or confirm Maps services are available on this Mac."
+        ) {
+            try await directions.calculate()
+        }
+
+        guard let route = routeResponse.routes.first else {
+            throw BridgeFailure(errorCode: "ROUTE_NOT_FOUND", message: "Apple Maps did not return a route.", suggestion: "Try a different transport mode or place query.")
+        }
+
+        return DirectionsPayload(
+            origin: placeRecord(originItem),
+            destination: placeRecord(destinationItem),
+            transport: transport,
+            distance_meters: route.distance,
+            expected_travel_time_seconds: route.expectedTravelTime,
+            advisory_notices: route.advisoryNotices
+        )
+    }
+
+    static func resolveFirstMapItem(query: String) async throws -> MKMapItem {
+        let request = MKLocalSearch.Request()
+        request.naturalLanguageQuery = query
+        let search = MKLocalSearch(request: request)
+        let response = try await withTimeout(
+            errorCode: "SEARCH_TIMEOUT",
+            message: "Apple Maps search timed out.",
+            suggestion: "Retry the query, or confirm Maps services are available on this Mac."
+        ) {
+            try await search.start()
+        }
+        guard let item = response.mapItems.first else {
+            throw BridgeFailure(errorCode: "PLACE_NOT_FOUND", message: "Apple Maps did not find a matching place.", suggestion: "Use a more specific address or place name.")
+        }
+        return item
+    }
+
+    static func placeRecord(_ item: MKMapItem) -> PlaceRecord {
+        let placemark = item.placemark
+        let formattedAddress = [placemark.subThoroughfare, placemark.thoroughfare, placemark.locality, placemark.administrativeArea, placemark.postalCode]
+            .compactMap { $0 }
+            .joined(separator: " ")
+
+        return PlaceRecord(
+            name: item.name ?? placemark.name ?? "Unknown",
+            address: formattedAddress.isEmpty ? nil : formattedAddress,
+            latitude: placemark.coordinate.latitude,
+            longitude: placemark.coordinate.longitude,
+            phone: item.phoneNumber,
+            url: item.url?.absoluteString
+        )
+    }
+
+    static func transportType(_ value: String) -> MKDirectionsTransportType {
+        switch value.lowercased() {
+        case "walking":
+            return .walking
+        case "transit":
+            return .transit
+        default:
+            return .automobile
+        }
+    }
+
+    static func decodeJSONObject(_ raw: String) throws -> [String: Any] {
+        guard
+            let data = raw.data(using: .utf8),
+            let payload = try JSONSerialization.jsonObject(with: data) as? [String: Any]
+        else {
+            throw BridgeFailure(errorCode: "INVALID_INPUT", message: "Expected a JSON object payload.", suggestion: "Pass a valid JSON object.")
+        }
+        return payload
+    }
+
+    static func string(_ value: Any?, field: String) throws -> String {
+        guard let text = value as? String, !text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+            throw BridgeFailure(errorCode: "INVALID_INPUT", message: "\(field) must be a non-empty string.", suggestion: "Provide the missing field.")
+        }
+        return text
+    }
+
+    static func int(_ value: Any?, field: String, defaultValue: Int) throws -> Int {
+        if value == nil {
+            return defaultValue
+        }
+        if let number = value as? Int {
+            return number
+        }
+        if let number = value as? NSNumber {
+            return number.intValue
+        }
+        throw BridgeFailure(errorCode: "INVALID_INPUT", message: "\(field) must be an integer.", suggestion: "Provide a numeric limit.")
+    }
+
+    static func withTimeout<T>(
+        errorCode: String,
+        message: String,
+        suggestion: String?,
+        operation: @escaping @Sendable () async throws -> T
+    ) async throws -> T {
+        try await withThrowingTaskGroup(of: T.self) { group in
+            group.addTask {
+                try await operation()
+            }
+            group.addTask {
+                let duration = UInt64(asyncTimeoutSeconds * 1_000_000_000)
+                try await Task.sleep(nanoseconds: duration)
+                throw BridgeFailure(errorCode: errorCode, message: message, suggestion: suggestion)
+            }
+            guard let result = try await group.next() else {
+                throw BridgeFailure(errorCode: errorCode, message: message, suggestion: suggestion)
+            }
+            group.cancelAll()
+            return result
+        }
+    }
+
+    static func writeErrorAndExit(_ failure: BridgeFailure) -> Never {
+        let payload = ErrorPayload(error_code: failure.errorCode, message: failure.message, suggestion: failure.suggestion)
+        if let data = try? encoder.encode(payload) {
+            FileHandle.standardError.write(data)
+        }
+        exit(1)
+    }
+}

apple_maps_mcp-1.0.0/src/apple_maps_mcp/config.py

@@ -0,0 +1,46 @@
+import os
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Settings:
+    server_name: str
+    version: str
+    helper_source: Path
+    helper_binary: Path
+    transport: str
+    host: str
+    port: int
+    log_level: str
+
+
+def _parse_int(value: str | None, default: int) -> int:
+    if value is None:
+        return default
+    try:
+        return int(value)
+    except ValueError:
+        return default
+
+
+@lru_cache(maxsize=1)
+def load_settings() -> Settings:
+    package_dir = Path(__file__).resolve().parent
+    build_dir = Path(
+        os.environ.get(
+            "APPLE_MAPS_MCP_HELPER_BUILD_DIR",
+            str(Path.home() / ".apple-mcps" / "build"),
+        )
+    ).expanduser()
+    return Settings(
+        server_name="Apple Maps MCP",
+        version="0.1.0",
+        helper_source=package_dir / "apple_maps_bridge.swift",
+        helper_binary=build_dir / "apple-maps-bridge",
+        transport=os.environ.get("APPLE_MAPS_MCP_TRANSPORT", "stdio").strip().lower() or "stdio",
+        host=os.environ.get("APPLE_MAPS_MCP_HOST", "127.0.0.1"),
+        port=_parse_int(os.environ.get("APPLE_MAPS_MCP_PORT"), 8000),
+        log_level=os.environ.get("APPLE_MAPS_MCP_LOG_LEVEL", "INFO").strip().upper() or "INFO",
+    )

apple_maps_mcp-1.0.0/src/apple_maps_mcp/maps_bridge.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import quote_plus, urlencode
+
+from apple_maps_mcp.config import load_settings
+
+
+@dataclass(frozen=True)
+class MapsBridgeError(Exception):
+    error_code: str
+    message: str
+    suggestion: str | None = None
+
+
+class AppleMapsBridge:
+    def __init__(self, helper_source: Path, helper_binary: Path) -> None:
+        self.helper_source = helper_source
+        self.helper_binary = helper_binary
+        self.timeout_seconds = 20
+
+    def helper_available(self) -> tuple[bool, bool]:
+        return self.helper_source.exists(), self.helper_binary.exists()
+
+    def _ensure_helper(self) -> None:
+        if not self.helper_source.exists():
+            raise MapsBridgeError(
+                "HELPER_SOURCE_MISSING",
+                f"Missing Apple Maps helper source at '{self.helper_source}'.",
+                "Reinstall apple-maps-mcp and retry.",
+            )
+        self.helper_binary.parent.mkdir(parents=True, exist_ok=True)
+        if self.helper_binary.exists() and self.helper_binary.stat().st_mtime >= self.helper_source.stat().st_mtime:
+            return
+        try:
+            subprocess.run(
+                ["swiftc", "-parse-as-library", "-O", str(self.helper_source), "-o", str(self.helper_binary)],
+                capture_output=True,
+                check=True,
+                text=True,
+                timeout=self.timeout_seconds,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise MapsBridgeError(
+                "HELPER_COMPILE_TIMEOUT",
+                "Timed out while compiling the Apple Maps helper.",
+                "Confirm Xcode command line tools are installed, then retry.",
+            ) from exc
+        except OSError as exc:
+            raise MapsBridgeError(
+                "SWIFTC_UNAVAILABLE",
+                f"Could not run 'swiftc': {exc}.",
+                "This server requires macOS with the Swift toolchain (swiftc) available.",
+            ) from exc
+        except subprocess.CalledProcessError as exc:
+            stderr = exc.stderr.strip() if exc.stderr else ""
+            raise MapsBridgeError(
+                "HELPER_COMPILE_FAILED",
+                stderr or "Failed to compile the Apple Maps helper.",
+                "Install Xcode command line tools and retry.",
+            ) from exc
+
+    def _run_helper(self, command: str, payload: dict[str, object]) -> dict[str, object]:
+        self._ensure_helper()
+        try:
+            result = subprocess.run(
+                [str(self.helper_binary), command, json.dumps(payload)],
+                capture_output=True,
+                check=True,
+                text=True,
+                timeout=self.timeout_seconds,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise MapsBridgeError(
+                "HELPER_TIMEOUT",
+                "Apple Maps helper timed out while waiting for MapKit.",
+                "Retry the request, or confirm Maps and Location Services are available on this Mac.",
+            ) from exc
+        except OSError as exc:
+            raise MapsBridgeError(
+                "HELPER_UNAVAILABLE",
+                f"Could not run the Apple Maps helper '{self.helper_binary}': {exc}.",
+                "This server requires macOS with the compiled Apple Maps helper available.",
+            ) from exc
+        except subprocess.CalledProcessError as exc:
+            stderr = exc.stderr.strip() or exc.stdout.strip()
+            raise MapsBridgeError("HELPER_FAILED", stderr or "Apple Maps helper failed.", "Retry the request.") from exc
+        try:
+            return json.loads(result.stdout)
+        except json.JSONDecodeError as exc:
+            raise MapsBridgeError("INVALID_RESPONSE", "Apple Maps helper returned invalid JSON.", "Retry the request.") from exc
+
+    def search_places(self, query: str, limit: int = 5) -> dict[str, object]:
+        return self._run_helper("search-places", {"query": query, "limit": limit})
+
+    def directions(self, origin: str, destination: str, transport: str = "driving") -> dict[str, object]:
+        payload = self._run_helper("directions", {"origin": origin, "destination": destination, "transport": transport})
+        payload["maps_url"] = self.maps_url(destination=destination, origin=origin, transport=transport)
+        return payload
+
+    def maps_url(self, destination: str, origin: str | None = None, transport: str = "driving") -> str:
+        params = {"daddr": destination}
+        if origin:
+            params["saddr"] = origin
+        transport_flag = {"driving": "d", "walking": "w", "transit": "r"}.get(transport, "d")
+        params["dirflg"] = transport_flag
+        return f"https://maps.apple.com/?{urlencode(params, quote_via=quote_plus)}"
+
+
+def build_bridge() -> AppleMapsBridge:
+    settings = load_settings()
+    return AppleMapsBridge(settings.helper_source, settings.helper_binary)

apple_maps_mcp-1.0.0/src/apple_maps_mcp/models.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ToolError(BaseModel):
+    error_code: str = Field(description="Stable machine-readable error code")
+    message: str = Field(description="Human-readable error message")
+    suggestion: str | None = Field(default=None, description="Suggested next step")
+
+
+class ErrorResponse(BaseModel):
+    ok: bool = False
+    error: ToolError
+
+
+class HealthResponse(BaseModel):
+    ok: bool = True
+    server_name: str
+    version: str
+    helper_available: bool
+    helper_compiled: bool
+    transport: str
+    capabilities: list[str]
+    supports: list[str]
+
+
+class PlaceRecord(BaseModel):
+    name: str
+    address: str | None = None
+    latitude: float | None = None
+    longitude: float | None = None
+    phone: str | None = None
+    url: str | None = None
+
+
+class PlaceSearchResponse(BaseModel):
+    ok: bool = True
+    places: list[PlaceRecord]
+    count: int
+
+
+class DirectionsResponse(BaseModel):
+    ok: bool = True
+    origin: PlaceRecord
+    destination: PlaceRecord
+    transport: str
+    distance_meters: float
+    expected_travel_time_seconds: float
+    advisory_notices: list[str]
+    maps_url: str
+
+
+class MapsLinkResponse(BaseModel):
+    ok: bool = True
+    url: str
+
+
+class OpenMapsResponse(BaseModel):
+    ok: bool = True
+    opened: bool
+    url: str

apple_maps_mcp-1.0.0/src/apple_maps_mcp/tools.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import json
+import subprocess
+
+from mcp.server.mcpserver import MCPServer
+from mcp.types import Annotations, ToolAnnotations
+
+from apple_maps_mcp.config import load_settings
+from apple_maps_mcp.maps_bridge import AppleMapsBridge, MapsBridgeError, build_bridge
+from apple_maps_mcp.models import DirectionsResponse, ErrorResponse, HealthResponse, MapsLinkResponse, OpenMapsResponse, PlaceRecord, PlaceSearchResponse, ToolError
+from apple_mcp_common.discovery import install_search_first_discovery
+
+SERVER_INSTRUCTIONS = (
+    "Use this server for Apple Maps and travel context on macOS. "
+    "Search here when the user wants to find a place, estimate travel time, build an Apple Maps link, or open directions in Apple Maps."
+)
+
+mcp = MCPServer("Apple Maps MCP", instructions=SERVER_INSTRUCTIONS)
+
+
+def _bridge() -> AppleMapsBridge:
+    return build_bridge()
+
+
+def _error_response(error_code: str, message: str, suggestion: str | None = None) -> ErrorResponse:
+    return ErrorResponse(error=ToolError(error_code=error_code, message=message, suggestion=suggestion))
+
+
+def _resource_json(value: object) -> str:
+    return json.dumps(value, indent=2, sort_keys=True, default=str)
+
+
+@mcp.resource(
+    "maps://status",
+    name="maps_status",
+    title="Maps Status",
+    description="Apple Maps helper availability and supported transport modes.",
+    mime_type="application/json",
+    annotations=Annotations(audience=["assistant"], priority=0.75),
+)
+def maps_status_resource() -> str:
+    helper_available, helper_compiled = _bridge().helper_available()
+    return _resource_json(
+        {
+            "helper_available": helper_available,
+            "helper_compiled": helper_compiled,
+            "supported_transports": ["driving", "walking", "transit"],
+        }
+    )
+
+
+@mcp.prompt(name="maps_plan_route", title="Plan Route")
+def maps_plan_route_prompt() -> str:
+    return (
+        "Use Apple Maps to find the right destination, estimate travel time, and choose the right transport mode "
+        "before scheduling a meeting or sending directions."
+    )
+
+
+@mcp.tool(
+    title="Maps Health",
+    description="Report the active Apple Maps MCP configuration.",
+    annotations=ToolAnnotations(read_only_hint=True, idempotent_hint=True),
+    structured_output=True,
+)
+def maps_health() -> HealthResponse:
+    settings = load_settings()
+    helper_available, helper_compiled = _bridge().helper_available()
+    return HealthResponse(
+        server_name=settings.server_name,
+        version=settings.version,
+        helper_available=helper_available,
+        helper_compiled=helper_compiled,
+        transport=settings.transport,
+        capabilities=[
+            "search_places",
+            "get_directions",
+            "build_maps_link",
+            "open_directions_in_maps",
+            "resources",
+            "prompts",
+        ],
+        supports=["stdio", "streamable-http"],
+    )
+
+
+@mcp.tool(
+    title="Maps Permission Guide",
+    description="Explain Apple Maps MCP local helper requirements on macOS.",
+    annotations=ToolAnnotations(read_only_hint=True, idempotent_hint=True),
+    structured_output=True,
+)
+def maps_permission_guide() -> dict[str, object]:
+    return {
+        "ok": True,
+        "domain": "maps",
+        "can_prompt_in_app": False,
+        "requires_manual_system_settings": False,
+        "steps": [
+            "Apple Maps MCP uses a local Swift helper for search and routing.",
+            "If helper compilation fails, install Xcode command line tools and retry.",
+            "Opening a route uses the standard macOS open command with an Apple Maps URL.",
+        ],
+    }
+
+
+@mcp.tool(
+    title="Search Places",
+    description="Search Apple Maps for matching places.",
+    annotations=ToolAnnotations(read_only_hint=True, idempotent_hint=True),
+    structured_output=True,
+)
+def maps_search_places(query: str, limit: int = 5) -> PlaceSearchResponse | ErrorResponse:
+    try:
+        payload = _bridge().search_places(query=query, limit=limit)
+        places = [PlaceRecord(**item) for item in payload.get("places", [])]
+        return PlaceSearchResponse(places=places, count=len(places))
+    except MapsBridgeError as exc:
+        return _error_response(exc.error_code, exc.message, exc.suggestion)
+
+
+@mcp.tool(
+    title="Get Directions",
+    description="Get Apple Maps route details between an origin and destination.",
+    annotations=ToolAnnotations(read_only_hint=True, idempotent_hint=True),
+    structured_output=True,
+)
+def maps_get_directions(origin: str, destination: str, transport: str = "driving") -> DirectionsResponse | ErrorResponse:
+    try:
+        payload = _bridge().directions(origin=origin, destination=destination, transport=transport)
+        return DirectionsResponse(
+            origin=PlaceRecord(**payload["origin"]),
+            destination=PlaceRecord(**payload["destination"]),
+            transport=str(payload["transport"]),
+            distance_meters=float(payload["distance_meters"]),
+            expected_travel_time_seconds=float(payload["expected_travel_time_seconds"]),
+            advisory_notices=[str(item) for item in payload.get("advisory_notices", [])],
+            maps_url=str(payload["maps_url"]),
+        )
+    except MapsBridgeError as exc:
+        return _error_response(exc.error_code, exc.message, exc.suggestion)
+
+
+@mcp.tool(
+    title="Build Maps Link",
+    description="Build an Apple Maps URL for a destination or route.",
+    annotations=ToolAnnotations(read_only_hint=True, idempotent_hint=True),
+    structured_output=True,
+)
+def maps_build_maps_link(destination: str, origin: str | None = None, transport: str = "driving") -> MapsLinkResponse:
+    return MapsLinkResponse(url=_bridge().maps_url(destination=destination, origin=origin, transport=transport))
+
+
+@mcp.tool(
+    title="Open Directions In Maps",
+    description="Open directions in the Apple Maps app.",
+    annotations=ToolAnnotations(destructive_hint=False, idempotent_hint=False, open_world_hint=True),
+    structured_output=True,
+)
+def maps_open_directions_in_maps(destination: str, origin: str | None = None, transport: str = "driving") -> OpenMapsResponse | ErrorResponse:
+    try:
+        url = _bridge().maps_url(destination=destination, origin=origin, transport=transport)
+        subprocess.run(["open", url], capture_output=True, check=True, text=True)
+        return OpenMapsResponse(opened=True, url=url)
+    except MapsBridgeError as exc:
+        return _error_response(exc.error_code, exc.message, exc.suggestion)
+    except subprocess.CalledProcessError:
+        return _error_response("OPEN_FAILED", "Failed to open Apple Maps.", "Retry the request.")
+    except OSError:
+        return _error_response("OPEN_UNAVAILABLE", "Could not run the 'open' command.", "This server requires macOS with the 'open' command available.")
+
+
+def _serialize_prompt_messages(messages: list[object]) -> list[dict[str, object]]:
+    return [
+        {
+            "role": getattr(message, "role", "user"),
+            "content": message.content.model_dump(mode="json") if hasattr(message.content, "model_dump") else message.content,
+        }
+        for message in messages
+    ]
+
+
+@mcp.tool(
+    title="Maps List Prompts",
+    description="Fallback prompt discovery tool for tool-only MCP clients.",
+    annotations=ToolAnnotations(read_only_hint=True, idempotent_hint=True),
+    structured_output=True,
+)
+async def maps_list_prompts() -> dict[str, object]:
+    prompts = await mcp.list_prompts()
+    return {
+        "ok": True,
+        "prompts": [{"name": prompt.name, "title": prompt.title, "description": prompt.description} for prompt in prompts],
+        "count": len(prompts),
+    }
+
+
+@mcp.tool(
+    name="maps_get_prompt",
+    title="Maps Get Prompt",
+    description="Fallback prompt rendering tool for tool-only MCP clients.",
+    annotations=ToolAnnotations(read_only_hint=True, idempotent_hint=True),
+    structured_output=True,
+)
+async def maps_get_prompt_prompt(name: str, arguments_json: str | None = None) -> dict[str, object]:
+    arguments = json.loads(arguments_json) if arguments_json else None
+    prompt = await mcp.get_prompt(name, arguments)
+    return {"ok": True, "name": name, "messages": _serialize_prompt_messages(prompt.messages), "message_count": len(prompt.messages)}
+
+
+TOOL_DISCOVERY = install_search_first_discovery(
+    mcp,
+    server_name="Apple Maps MCP",
+    domain="maps",
+)
+
+
+def main() -> None:
+    settings = load_settings()
+    if settings.transport == "stdio":
+        mcp.run(transport="stdio")
+        return
+    mcp.settings.log_level = settings.log_level
+    mcp.run(
+        transport="streamable-http",
+        host=settings.host,
+        port=settings.port,
+        json_response=True,
+        stateless_http=True,
+    )

apple_maps_mcp-1.0.0/src/apple_maps_mcp.egg-info/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: apple-maps-mcp
+Version: 1.0.0
+Summary: Local Apple Maps MCP server for macOS
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JonathanRReed/Apple-MCPs
+Project-URL: Repository, https://github.com/JonathanRReed/Apple-MCPs
+Project-URL: Changelog, https://github.com/JonathanRReed/Apple-MCPs/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/JonathanRReed/Apple-MCPs/issues
+Keywords: mcp,model-context-protocol,macos,apple,ai-agent,automation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: apple-mcp-common<2,>=1.0.0
+Requires-Dist: mcp<3,>=2.0.0
+Requires-Dist: pydantic>=2.12.0
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: ruff<1,>=0.12; extra == "dev"
+Dynamic: license-file
+
+<!-- mcp-name: io.github.jonathanrreed/apple-maps-mcp -->
+
+# Apple Maps MCP
+
+Local MCP server for Apple Maps search and routing on macOS.
+
+## Capabilities
+
+- search for places
+- estimate route distance and travel time
+- build Apple Maps links
+- open directions in Apple Maps
+- resource: `maps://status`
+- prompt: `maps_plan_route`
+- tool discovery helpers `search_tools` and `get_tool_info` for context-constrained clients
+
+## Install On This Mac
+
+<details>
+<summary>Quick start (uvx, from PyPI)</summary>
+
+With [uv](https://docs.astral.sh/uv/getting-started/installation/) installed:
+
+```bash
+uvx apple-maps-mcp
+```
+
+No clone, no venv management.
+
+</details>
+
+<details>
+<summary>From a clone</summary>
+
+```bash
+git clone https://github.com/JonathanRReed/Apple-MCPs.git
+cd Apple-MCPs
+uv sync --all-packages
+```
+
+This builds one workspace environment with every server's entry point in `.venv/bin` (for example `.venv/bin/apple-maps-mcp`). You can also point an MCP client at `AppleMaps-MCP/start.sh`, which prefers `uv run` and falls back to a plain venv bootstrap (Python 3.11+ required).
+
+</details>
+
+## Install In AI Agents
+
+```json
+{
+  "mcpServers": {
+    "apple-maps": {
+      "command": "uvx",
+      "args": ["apple-maps-mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+Running from a clone instead? Use `/path/to/Apple-MCPs/AppleMaps-MCP/start.sh` as the command with empty `args`.
+
+Claude Code:
+
+```bash
+claude mcp add --transport stdio --scope project apple-maps -- uvx apple-maps-mcp
+```
+
+## Transport
+
+`stdio` is the default and recommended transport. Set `APPLE_MAPS_MCP_TRANSPORT=streamable-http` (with optional `APPLE_MAPS_MCP_HOST` and `APPLE_MAPS_MCP_PORT`) to serve Streamable HTTP instead.
+
+## Prompting Notes
+
+- `tools/list` returns the full Maps tool surface. Context-constrained clients can use `search_tools` first, then `get_tool_info` for the Maps tool they need.
+- Use this server when travel, routing, or place lookup affects a Calendar, Reminders, Messages, or Mail action.
+- Confirm origin, destination, and transport mode before writing a time-sensitive plan.
+- If helper compilation fails, install Xcode command line tools and retry.
+
+## Health And Recovery
+
+- `maps_health`
+- `maps_permission_guide`
+
+## Launch Checklist
+
+- Add `uvx apple-maps-mcp` (or a clone's `AppleMaps-MCP/start.sh`) to your MCP client
+- Reload or reconnect the client so the Maps tool surface is loaded into context
+- Call `maps_health` first
+- If the local helper or routing surface is blocked, call `maps_permission_guide`
+- Run `maps_search_places` once to confirm the local Swift helper compiles

apple_maps_mcp-1.0.0/src/apple_maps_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+src/apple_maps_mcp/__init__.py
+src/apple_maps_mcp/apple_maps_bridge.swift
+src/apple_maps_mcp/config.py
+src/apple_maps_mcp/maps_bridge.py
+src/apple_maps_mcp/models.py
+src/apple_maps_mcp/tools.py
+src/apple_maps_mcp.egg-info/PKG-INFO
+src/apple_maps_mcp.egg-info/SOURCES.txt
+src/apple_maps_mcp.egg-info/dependency_links.txt
+src/apple_maps_mcp.egg-info/entry_points.txt
+src/apple_maps_mcp.egg-info/requires.txt
+src/apple_maps_mcp.egg-info/top_level.txt
+tests/test_bridge.py
+tests/test_config.py
+tests/test_tools.py

apple_maps_mcp-1.0.0/src/apple_maps_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

apple_maps_mcp-1.0.0/src/apple_maps_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+apple-maps-mcp = apple_maps_mcp.tools:main

apple_maps_mcp-1.0.0/src/apple_maps_mcp.egg-info/requires.txt

@@ -0,0 +1,7 @@
+apple-mcp-common<2,>=1.0.0
+mcp<3,>=2.0.0
+pydantic>=2.12.0
+
+[dev]
+pytest<10,>=8
+ruff<1,>=0.12

apple_maps_mcp-1.0.0/src/apple_maps_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+apple_maps_mcp

apple_maps_mcp-1.0.0/tests/test_bridge.py

@@ -0,0 +1,22 @@
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from apple_maps_mcp.maps_bridge import AppleMapsBridge, MapsBridgeError
+
+
+def test_run_helper_maps_timeout_to_structured_error(monkeypatch) -> None:
+    bridge = AppleMapsBridge(Path("/tmp/apple_maps_bridge.swift"), Path("/tmp/apple-maps-bridge"))
+
+    monkeypatch.setattr(bridge, "_ensure_helper", lambda: None)
+
+    def fake_run(*args, **kwargs):
+        raise subprocess.TimeoutExpired(cmd="apple-maps-bridge", timeout=20)
+
+    monkeypatch.setattr(subprocess, "run", fake_run)
+
+    with pytest.raises(MapsBridgeError) as exc_info:
+        bridge.search_places("coffee")
+
+    assert exc_info.value.error_code == "HELPER_TIMEOUT"

apple_maps_mcp-1.0.0/tests/test_config.py

@@ -0,0 +1,15 @@
+from apple_maps_mcp.config import load_settings
+
+
+def test_load_settings_uses_packaged_helper_source() -> None:
+    load_settings.cache_clear()
+
+    try:
+        settings = load_settings()
+    finally:
+        load_settings.cache_clear()
+
+    assert settings.helper_source.name == "apple_maps_bridge.swift"
+    assert settings.helper_source.parent.name == "apple_maps_mcp"
+    assert settings.helper_source.exists()
+    assert settings.helper_binary.name == "apple-maps-bridge"

apple_maps_mcp-1.0.0/tests/test_tools.py

@@ -0,0 +1,75 @@
+from apple_maps_mcp import tools
+
+
+class StubBridge:
+    def helper_available(self):
+        return True, True
+
+    def search_places(self, query: str, limit: int = 5):
+        return {"places": [{"name": "Coffee Shop", "address": "123 Main St", "latitude": 30.0, "longitude": -97.0, "phone": None, "url": None}]}
+
+    def directions(self, origin: str, destination: str, transport: str = "driving"):
+        return {
+            "origin": {"name": origin, "address": origin, "latitude": 30.0, "longitude": -97.0, "phone": None, "url": None},
+            "destination": {"name": destination, "address": destination, "latitude": 30.1, "longitude": -97.1, "phone": None, "url": None},
+            "transport": transport,
+            "distance_meters": 1000,
+            "expected_travel_time_seconds": 600,
+            "advisory_notices": [],
+            "maps_url": "https://maps.apple.com/?daddr=Coffee+Shop",
+        }
+
+    def maps_url(self, destination: str, origin: str | None = None, transport: str = "driving"):
+        return "https://maps.apple.com/?daddr=Coffee+Shop"
+
+
+def test_maps_search_places(monkeypatch):
+    monkeypatch.setattr(tools, "_bridge", lambda: StubBridge())
+    result = tools.maps_search_places("coffee")
+    assert result.ok is True
+    assert result.count == 1
+    assert result.places[0].name == "Coffee Shop"
+
+
+def test_maps_build_maps_link(monkeypatch):
+    monkeypatch.setattr(tools, "_bridge", lambda: StubBridge())
+    result = tools.maps_build_maps_link("Coffee Shop")
+    assert result.url.startswith("https://maps.apple.com/")
+
+
+def test_maps_status_resource(monkeypatch):
+    monkeypatch.setattr(tools, "_bridge", lambda: StubBridge())
+    payload = tools.maps_status_resource()
+    assert "\"helper_available\": true" in payload
+    assert "\"driving\"" in payload
+
+
+def test_main_uses_streamable_http(monkeypatch):
+    monkeypatch.setenv("APPLE_MAPS_MCP_TRANSPORT", "streamable-http")
+    monkeypatch.setenv("APPLE_MAPS_MCP_HOST", "0.0.0.0")
+    monkeypatch.setenv("APPLE_MAPS_MCP_PORT", "8765")
+    monkeypatch.setenv("APPLE_MAPS_MCP_LOG_LEVEL", "DEBUG")
+    tools.load_settings.cache_clear()
+
+    captured = {}
+
+    def fake_run(*, transport: str, host: str, port: int, json_response: bool, stateless_http: bool):
+        captured["transport"] = transport
+        captured["host"] = host
+        captured["port"] = port
+        captured["json_response"] = json_response
+        captured["stateless_http"] = stateless_http
+        captured["log_level"] = tools.mcp.settings.log_level
+
+    monkeypatch.setattr(tools.mcp, "run", fake_run)
+
+    tools.main()
+
+    assert captured == {
+        "transport": "streamable-http",
+        "host": "0.0.0.0",
+        "port": 8765,
+        "json_response": True,
+        "stateless_http": True,
+        "log_level": "DEBUG",
+    }