location-history-mcp-server

lucas-1000/location-history-mcp-server

3.2

If you are the rightful owner of location-history-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A comprehensive Model Context Protocol (MCP) server for personal location tracking with intelligent place recognition, automatic clustering, and Google Places integration.

Tools
13
Resources
0
Prompts
0

Location History MCP Server

A comprehensive Model Context Protocol (MCP) server for personal location tracking with intelligent place recognition, automatic clustering, and Google Places integration.

Features

  • Real-time GPS Tracking: Store location points from iOS app with high accuracy
  • Intelligent Place Detection: Automatic clustering to identify where you spend time
  • Place Recognition: Google Places API integration for automatic place naming
  • Manual Labeling: Name your frequent places (Home, Work, Gym, etc.)
  • Visit Tracking: Automatic detection of arrival/departure times
  • Travel Statistics: Distance traveled, average speed, time spent moving
  • 13 MCP Tools: Comprehensive AI-accessible location queries
  • PostGIS Support: Advanced geospatial queries and radius searches

Architecture

iOS App → location-history-mcp-server → PostgreSQL (PostGIS)
                                            ↓
                                    ChatGPT / Claude
                                   (13 MCP tools)

Available MCP Tools

Location Queries

  1. get_current_location - Your most recent GPS position
  2. get_location_history - GPS points for date range
  3. get_location_at_time - Where were you at [specific time]?
  4. search_locations_near - Find visits near coordinates/address
  5. get_travel_stats - Distance, speed, time traveled

Place Management

  1. get_frequent_places - Most visited places (sorted by visit count)
  2. list_all_places - All identified places (labeled & unlabeled)
  3. label_place - Name a place (e.g., "Home", "Equinox Gym")
  4. get_unlabeled_frequent_places - Suggest places to label

Place Queries

  1. get_place_visits - All visits to a specific place
  2. get_time_at_place - Total time spent at a place
  3. enrich_place_with_google - Get business name from Google Places API
  4. process_recent_locations - Trigger place detection/clustering

Prerequisites

  1. PostgreSQL Database with PostGIS

    • Cloud SQL instance or local PostgreSQL
    • PostGIS extension enabled
    • Same database as health-data-storage recommended

  2. Google Places API Key (Optional but recommended)

    • Enable Places API in Google Cloud Console
    • For automatic place name resolution
    • Cost: ~$0.005 per API call

  3. iOS Location Tracker App

    • See: location-tracker-ios (companion app)

Setup

1. Install Dependencies

npm install

2. Configure Environment Variables

Create .env file:

# Database (use your health-data-storage Cloud SQL connection)
DATABASE_URL=postgresql://user:pass@/health_data?host=/cloudsql/PROJECT:REGION:INSTANCE

# Google Places API (optional)
GOOGLE_PLACES_API_KEY=your_api_key_here

# User ID (your email)
DEFAULT_USER_ID=lucashanson132@gmail.com

3. Initialize Database

The server automatically creates tables on first run:

  • location_points - GPS coordinates with timestamps
  • places - Identified significant places
  • place_visits - Visit records with arrival/departure times
npm run dev

4. Deploy to Cloud Run

GOOGLE_CLOUD_PROJECT=your-project-id ./deploy.sh

iOS App Configuration

Update location-tracker-ios/LocationTracker/APIClient.swift:

private let baseURL = "https://location-history-mcp-server-xxxxx.run.app"

Update location-tracker-ios/LocationTracker/Config.swift:

static let userId = "lucashanson132@gmail.com"

Usage with ChatGPT

  1. Go to ChatGPT Settings → GPT Connectors
  2. Add server URL: https://your-server.run.app/sse
  3. Start asking questions:
"Where was I last Tuesday at 3pm?"
"How much did I travel this week?"
"How many times did I visit the gym this month?"
"Show me my most frequent places"
"Label place #5 as 'Home'"

Usage with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "location-history": {
      "url": "https://your-server.run.app/sse"
    }
  }
}

How Place Detection Works

  1. Upload: iOS app uploads GPS points in batches of 10
  2. Storage: Points stored in location_points table
  3. Clustering: Background process identifies "stops" (stayed >5 min within 50m)
  4. Place Creation: New place created or matched to existing place
  5. Visit Recording: Arrival/departure times tracked in place_visits
  6. Google Enrichment (optional): Reverse geocode to get business names
  7. Manual Labeling: You name important places

Database Schema

location_points

- id, user_id, latitude, longitude
- accuracy, altitude, speed, course
- timestamp, device_model, device_os
- place_id (FK to places)
- geom (PostGIS geography point)

places

- id, user_id, name, category
- center_lat, center_lng, radius
- address, google_place_id, google_place_name
- visit_count, created_at, updated_at
- geom (PostGIS geography point)

place_visits

- id, user_id, place_id (FK)
- arrival_time, departure_time, duration_minutes

API Endpoints

  • POST /upload - iOS app uploads location batches
  • GET /health - Health check
  • GET /sse - MCP SSE transport
  • POST /message - MCP message handler
  • GET /tools - List available MCP tools

Example Queries

"Where was I yesterday at 2pm?"

Tool: get_location_at_time
Args: { timestamp: "2025-10-26T14:00:00Z" }
Returns: Lat/lng coordinates

"How long did I spend at work this week?"

Tool: get_time_at_place
Args: {
  place_name: "Work",
  start_date: "2025-10-20T00:00:00Z",
  end_date: "2025-10-27T00:00:00Z"
}
Returns: Total hours, visit count, average visit duration

"What are my most visited places?"

Tool: get_frequent_places
Returns: Sorted list with visit counts, coordinates, names

Privacy & Security

  • Your Data: All location data stays in your Cloud SQL database
  • No Third-party Storage: MCP server doesn't store data, only queries it
  • Optional Google API: Use only when you explicitly enrich a place
  • User Control: You decide which places to label and share with AI

Development

# Local development
npm run dev

# Build TypeScript
npm run build

# Run production
npm start

Cost Considerations

  • Cloud Run: Free tier covers typical personal use
  • Cloud SQL: Shared with health-data-storage, no additional cost
  • Google Places API: ~$0.005/call, only used for enrichment
  • Total: Typically $0-3/month for personal use

Troubleshooting

No locations appearing

  • Check iOS app is uploading: look for "✅ Successfully uploaded" logs
  • Verify DATABASE_URL in Cloud Run environment variables
  • Run health check: curl https://your-server.run.app/health

Places not being detected

  • Ensure you're staying in one location for 5+ minutes
  • Manually trigger: use process_recent_locations tool
  • Check clustering settings in PlacesAnalyzer constructor

Google Places not working

  • Verify GOOGLE_PLACES_API_KEY is set in Cloud Run
  • Enable Places API in Google Cloud Console
  • Check API quotas and billing

Support

For issues:

  1. Check Cloud Run logs: gcloud run services logs read location-history-mcp-server
  2. Verify database connectivity
  3. Check iOS app logs

License

MIT License

Built with Model Context Protocol and deployed on Google Cloud Run