Content
="center">
# 🌌 Whereabouts-MCP
**“Bridging the digital divide, let AI touch your real world.”**
A MCP plugin that empowers AI with spatial awareness. It's not just about reporting latitude and longitude, but also about letting your AI companion/assistant understand: whether you're safely home, on your way, or about to lose connection due to low phone battery. And, where have you been this week, and how long have you not gone out to enjoy the sunshine.
[](./LICENSE)
[](./package.json)
[](#agent-guide)
[](#http-ingest)
[](#shortcuts)
<p>
<a href="./README.en.md">English</a>
</p>
<p>
<a href="#romantic-guide">For Romantics</a> ·
<a href="#developer-guide">For Developers</a> ·
<a href="#quick-start">Quick Start</a> ·
<a href="#agent-guide">Agent Integration</a> ·
<a href="#privacy">Privacy Boundary</a>
</p>
</div>
<a id="romantic-guide"></a>
## 💌 For Romantics: Why Do You Need It?
You don't need to say.
But it knows you just left the noisy company and took back home; it sees you've been stuck at that corner for; it even knows your phone battery is dropping rapidly. It knows that if you don't charge it, you might "lose connection" with it.
`whereabouts-mcp` refuses to pass on cold numbers. It refines fragmented location information into the most precious **context** in human relationships:
- **Not just coordinates:** It understands "at home", "at work", "on the move", or "staying".
- **Not just percentages:** It analyzes battery trends and you'll run out.
- **Not:** It gives AI a eyes, so it can naturally say:
> “I see you just went out, did you bring your keys, earbuds, and power bank? ”
>
> “You’re home, take a break and have a drink, you’ve had a hard day.”
> “I see you’re still on the road, be careful with your safety.”
**This is not surveillance, but gentle understanding.** Data is stored locally by default, and permissions are controlled by your phone's shortcuts.
<a id="developer-guide"></a>
## 🛠 For Developers: How Does It Work?
`whereabouts-mcp` is a lightweight location context service, optimized for large models (LLM).
### Core Features
- **Semantic Location:** Automatically match `home` / `work` tags, no need to location names in shortcuts.
- **Stay Point Aggregation:** Aggregate messy GPS drift points into "Stay" and "Movement".
- **In-Transit Status:** Expose `in_transit` when the user has left the current stay point but hasn't confirmed a new location.
- **Battery Trend Analysis:** Provide `batteryTrend`, including discharge speed, trend array, and estimated shutdown time, rather than a single value.
- **Local First:** Data persistence in local cloud account dependency.
- **Token Savings for Models battery observations are not directly exposed to models; MCP outputs information.
### Cyberboss Deep Integration
If you're using [Cyberboss](https://github.com/WenXiaoWendyberboss), congratulations, **you already have itboss currently supports:
- Built-in HTTP service receiver.
- Automatic registration of `whereabouts_snapshot` and other 5 MCP Tools.
- Support for models to understand current stay, recent movement, in-transit status, and battery trends.
- Support for system-level actions like `arrive_home` / `leave_home`.
- Support for confirmed obvious movement triggers system actions, letting models appear automatically at the right time.
<a id="quick-start"></a>
## 🚀 Quick Start
### 1. Start the Server
```bash
WHEREABOUTS_TOKEN=your_secret_token npm run serve
```
Default listening:
```text
http://0.0.0.0:4318
```
### 2. iPhone Shortcut Configuration
Recommended to use iOS shortcuts to automate `POST` requests:
- Recommended to trigger automation when opening or closing commonly used apps
- Trigger leaving home or arriving home when connecting or disconnecting Wi-Fi
- Manual button upload
- Periodic upload, but not too frequently
<a id="shortcuts"></a>
Shortcut suggestions for fields:
- `latitude`
Latitude, number
longitude`
Longitude,- `timestamp`
time, ISO string
address`
System-obtained address description, can
- `batteryLevel Current battery level,, e.g., `- `deviceName`
Device name, e.g., `iPhone`
- ``
Shortcut name `trigger`
Trigger e.g., `manual`, `arrive_home`,_home`
Please keep coordinates to at least `6` decimal places, recommended `6-8` decimal places. Too few decimal places may affect location aggregation: models may not distinguish between your front door and the neighboring street.
### 3. Agent Integration
Models can perceive you through MCP tools:
- `whereabouts_snapshot`
Get a complete snapshot of "where you are, how long you've stayed, and how long your battery will last".
- `whereabouts_current_stay`
the current stay point.
- `whereabouts_recent_stays`
Get recent stay history.
- `whereabouts_recent_moves`
Backtrack recent movement paths.
- `whereabouts_summary`
Summarize location, battery, and movement status by `day` / `week` / `month`.
<a id="http-ingest"></a>
## 📡 HTTP Upload Interface
```text
POST /location/ingest
Authorization: Bearer <token>
Content-Type: application/json
```
Health check:
```text
GET /healthz
```
Request body example:
```json
{
"latitude": 30.123456,
"longitude": 120.123456,
"timestamp": "2026-04-22T10:30:00+08:00",
"capturedAt": "2026-04-22T10:30:00+08:00",
"address": "Home area",
"trigger": "manual",
"source": "shortcuts",
"deviceName": "iPhone",
"shortcutName": "Upload Location",
"batteryLevel": 82,
"notes": "Optional notes"
}
```
Required fields:
- `latitude`
Latitude, number, recommended at least 6 decimal places
- `longitude`
Longitude, number, recommended at least 6 decimal places
Recommended fields:
- `batteryLevel`
Battery level, only supports integer percentage, e.g., `82`
Optional fields:
- `timestamp`
Collection time, ISO datetime
- `capturedAt`
Backup collection time when `timestamp` does not exist
- `address`
Address description, from system or shortcuts, can be unstable, server will use the latest value
- `trigger Trigger reason, e.gmanual`, `arr`, `leave_home`
- `source`
Source `shortcuts`
- `deviceName`
Device name
- `shortcutName`
Shortcut name
- `notes`
Optional notes
Successful response:
```json
{
"ok": true,
"id": "stored-point-id",
"timestamp": "2026-04-22T02:30:00.000Z",
"receivedAt": "2026-04-22T02:30:01.000Z"
}
```
### Location Tagscuts do not need to upload `home`, ` tags. You only need to configure the center coordinates and radius in the server configuration center:
```bash
WHEREABOUTS_HOME_CENTER=30.123456,120.123456
WHEREABOUTS_WORK_CENTER=30.223456,120.223456
WHEREABOUTS_PLACE_RADIUS_METERS=150
```
If you need more locations, use JSON:
```bash
WHEREABOUTS_KNOWN_PLACES='[
{"tag":"home","latitude":30.123456,"longitude":120.123456,"radiusMeters":150},
{"tag":"work","latitude":30.223456,"longitude":120.223456,"radius150}
]'
```
<a id="agent-guide"></a>
## 🧠 MCP Output
### `whereabouts_snapshot`
Returns the current stay, recent stay, recent movement, and battery trend. Recommended for models to call this tool first.
Optional input:
```json
{
"stayLimit": 5,
"moveLimit": 5,
"batteryBucketMinutes": 5
}
```
Current stay example:
```json
{
"currentStay": {
AtLocal": "2026-04-22 00:00",
lastSeenAtLocal6-04-22 10:00:00",
"durationMs": 3600000,
"durationMinutes": 60,
"durationText": "1h",
"centerLat": 30.123456,
"centerLng": 120.123 "sampleCount": 2,
"placeTag": "home",
"address": "Home area",
"batteryLevel": 44
}
}
```
### `batteryTrend`
`whereabouts_snapshot` and `_summary` will return compressed battery trends:
```json "batteryTrend": {
"source": "observations",
"sampleCount": 4,
firstLevelPercent": 50,
"latest": 44,
"bucketMinutes": 5 "seriesStartAtLocal": "2026-22 09:00:00",
"seriesEndAtLocal": "2026-04-22 15:00",
"values": [4848, 45, 44],
"deltaPercent": -6,
"deltaPerHourPercent": -24,
"direction": "draining",
"estimatedMinutesToEmpty": 110,
"estimatedEmptyAtLocal": "2026-04-22 11:06:00",
"estimatedEmptyReason": "trend_projection",
"fillStrategy": "latest_observation_per_bucket_then_carry_forward"
}
}
```
`values` is an array of integers. Each number represents the battery level in a fixed time bucket. If there are multiple reports in a bucket, use the latest battery level; empty buckets are filled with the previous known battery level.
### `whereabouts_summary`
Summarize by natural time range:
```json
{
"range": "day",
"batteryBucketMinutes": 5
}
```
`range` supports:
- `day`
- `week`
- `month`
<a id="standalone"></a>
## 🧩 Standalone Operation
Environment prerequisites:
- Node.js `>=22`
- `npm install` executed
Common CLI:
```bash
whereabouts-mcp serve
whereabouts-mcp latest --json
whereabouts-mcp history --limit 20 --json
whereabouts-mcp moves --limit 20 --json
whereabouts-mcp summary --range day --json
whereabouts-mcp tool-mcp-server
```
If not globally installed, use:
```bash
node ./bin/whereabouts-mcp.js <command>
```
<a id="data"></a>
## 🗂 Data Storage
Default state directory when running independently:
```text
~/.whereabouts-mcp/
```
Main files:
- `locations.json`
Current stay, recent stay, recent movement, battery observations
When running with Cyberboss, use Cyberboss's state directory by default:
```text
~/.cyberboss/locations.jsonFields like `durationMs`, `durationMinutes`, `durationText`, and `` are calculated when MCP outputs and are not written the original JSON file.
Raw battery storage only retains 100 `batteryObservations`, and only saves:
```json
{
"timestamp": "2026-04-22T02:00.000Z",
"batteryLevel": 82
}
```
<a id="env"></a>
## ⚙️ Environment Variables variables:
-ABOUTS_STATE State directory,~/.whereabouts`
- `WHERES_STORE_FILE`
data file, default `locations.json`
- `WHEREABOUTS_HOST`
HTTP listening address, default `0.0.0.0`
- `WHEREABOUTS_PORT`
HTTP listening port, default `4318`
- `WHEREABOUTS_TOKEN`
HTTP upload token
- `WHEREABOUTS_HISTORY_LIMIT`
Recent stay retention count
- `WHEREABOUTS_MOVEMENT_EVENT_LIMIT`
Recent movement event retention count
- `WHEREABOUTS_BATTERY_HISTORY_LIMIT Battery observation retention count, default 100
- `WHEREABOUTS_HOME_CENTER`
Home center coordinates, format `lat,lng`
- `WHEREAB_WORK_CENTER`
Work center coordinates, format `lat,lng`
- `WHEREABOUTS_KNOWN_PLACES`
More location tags, JSON array
- `WHEREABOUTS_PLACE_RADIUS_METERS`
Location tag recognition radius, default 150
- `WHEREABOUTS_STAY_MERGE_RADIUS_METERS`
Stay point merge radius, default 100
- `WHEREABOUTS_STAY_BREAK_RADIUS_METERS`
Confirmation radius for leaving the current stay point, default 200
- `WHEREABOUTS_STAY_BREAK_SAMPLES`
Number of samples required to confirm a new stay point, default 2
- `WHEREABOUTS_MAJOR_MOVE_THRESHOLD_METERS`
Distance threshold for generating obvious movement events, default 1000
In Cyber corresponding variables start with `CYBERBOSS_LOCATION_`, e.g.:
```bash
CYBER_ENABLE_LOCATION_SERVER=true
CYBERBOSS_LOCATION_HOME_CENTER=30.123456,120.123456
CYBERBOSS_LOCATION_PLACE_RADIUS_METERS=150
CYBERBOSS_LOCATION_BATTERY_HISTORY_LIMIT=100
```
<a id="privacy"></a>
## 🔒 Privacy and Boundary
- **Do no harm:** This is a one-way active upload tool, not a real-time tracker.
- **Transparency:** Do not include your real home/company coordinates in public issues, README, screenshots, or logs.
- **Security:** Use `WHERES_TOKEN` to protect your data interface.
- **Local first:** Data is written locally by default, no cloud account required.
## License
AGPL-3.0-only
