location-history-mcp-server

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

1. 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

1. 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