MCP Google Maps

Instructions

Implementation Reference

• src/services/map-directions.ts:109-167 (handler)

  Core handler function implementing the tool logic: validates input parameters, generates Google Maps directions URL and static map URL with markers and path overlay.

  async getMapWithDirections(
      params: MapDirectionsParams
  ): Promise<ServiceResponse<MapDirectionsResponse>> {
      try {
          // Validate required fields
          if (
              !params.origin ||
              !params.origin.lat ||
              !params.origin.lng ||
              !params.origin.address
          ) {
              throw new Error("Origin must include address, lat, and lng");
          }
          if (
              !params.destination ||
              !params.destination.lat ||
              !params.destination.lng ||
              !params.destination.address
          ) {
              throw new Error(
                  "Destination must include address, lat, and lng"
              );
          }
  
          // Validate waypoints if provided
          if (params.waypoints) {
              for (const wp of params.waypoints) {
                  if (!wp.lat || !wp.lng || !wp.address) {
                      throw new Error(
                          "Each waypoint must include address, lat, and lng"
                      );
                  }
              }
          }
  
          // Generate URLs
          const googleMapsUrl = this.buildGoogleMapsUrl(params);
          const staticMapUrl = this.generateStaticMapUrl(params);
  
          // Create summary
          const summary = {
              origin: params.origin.address,
              destination: params.destination.address,
              waypoints: params.waypoints?.map((wp) => wp.address),
              mode: params.mode || TravelMode.driving,
          };
  
          return {
              success: true,
              data: {
                  googleMapsUrl,
                  staticMapUrl,
                  summary,
              },
          };
      } catch (error) {
          return handleError(error);
      }
  }

• src/mcp/create-server.ts:275-309 (registration)

  Tool registration in MCP server, proxying to MapDirectionsService.getMapWithDirections with error handling and response formatting.

  server.registerTool(
      "get_map_with_directions",
      {
          title: "Map with Directions",
          description: "Generate a static map with directions overlay",
          inputSchema: MapWithDirectionsSchema,
      },
      async (args) => {
          try {
              const result = await mapDirectionsService.getMapWithDirections({
                  ...args,
                  mode: args.mode as TravelMode | undefined,
              });
              return {
                  content: [
                      { type: "text", text: JSON.stringify(result, null, 2) },
                  ],
                  isError: !result.success,
              };
          } catch (error) {
              const errorResponse = handleError(error);
              return {
                  content: [
                      {
                          type: "text",
                          text:
                              errorResponse.error ||
                              "An unknown error occurred",
                      },
                  ],
                  isError: true,
              };
          }
      }
  );

• src/schemas/tool-schemas.ts:50-73 (schema)

  Zod input schema defining parameters for origin, destination, optional waypoints, travel mode, map size, etc.

  export const MapWithDirectionsSchema = {
    origin: z.object({
      address: z.string(),
      lat: z.number(),
      lng: z.number()
    }),
    destination: z.object({
      address: z.string(),
      lat: z.number(),
      lng: z.number()
    }),
    waypoints: z.array(z.object({
      address: z.string(),
      lat: z.number(),
      lng: z.number()
    })).optional(),
    mode: TravelModeSchema.optional(),
    size: z.object({
      width: z.number(),
      height: z.number()
    }).optional(),
    scale: z.number().optional(),
    mapType: z.enum(["roadmap", "satellite", "hybrid", "terrain"]).optional()
  };

• src/services/map-directions.ts:59-104 (helper)

  Helper function to generate the static Google Maps image URL with colored markers for origin/waypoints/destination and a connecting path.

  private generateStaticMapUrl(params: MapDirectionsParams): string {
      const baseUrl = "https://maps.googleapis.com/maps/api/staticmap";
  
      // Build all locations array
      const allLocations = [
          params.origin,
          ...(params.waypoints || []),
          params.destination,
      ];
  
      // Create markers
      const markers = [
          // Origin marker (green, label A)
          `markers=size:mid|color:green|label:A|${params.origin.lat},${params.origin.lng}`,
          // Destination marker (red, with appropriate letter)
          `markers=size:mid|color:red|label:${String.fromCharCode(65 + allLocations.length - 1)}|` +
              `${params.destination.lat},${params.destination.lng}`,
      ];
  
      // Add waypoint markers (blue, labels B, C, etc.)
      if (params.waypoints) {
          params.waypoints.forEach((wp, i) => {
              markers.push(
                  `markers=size:mid|color:blue|label:${String.fromCharCode(66 + i)}|${wp.lat},${wp.lng}`
              );
          });
      }
  
      // Create path connecting all points
      const pathPoints = allLocations
          .map((loc) => `${loc.lat},${loc.lng}`)
          .join("|");
      const path = `path=color:0x4285F4|weight:4|${pathPoints}`;
  
      // Build URL parameters
      const urlParams = new URLSearchParams({
          key: config.googleMapsApiKey,
          size: `${params.size?.width || 640}x${params.size?.height || 480}`,
          scale: (params.scale || 2).toString(),
          maptype: params.mapType || "roadmap",
      });
  
      // Combine everything
      // Caution !!!Do not send this URL to the client directly, as it contains API key!!!
      return `${baseUrl}?${urlParams}&${markers.join("&")}&${path}`;
  }