Developer Documentation

Soma documentation

Connect Claude, ChatGPT, Cursor, OpenClaw, Hermes, or any MCP-compatible AI agent to your iPhone’s Apple Health and Core Location data through a local Model Context Protocol server running on your Mac.

Quick start

Install Soma for iPhone. Grant the health and location permissions Soma requests. Data begins syncing to your personal iCloud container on first launch.
Install Soma Companion for Mac. Sign in with the same Apple ID. The menubar app starts a local MCP server on localhost:8741.
Connect your AI agent. Add Soma as an MCP server in your agent’s configuration (examples below). The agent gains access to the tool calls listed in the tool reference.
Ask a question. Try “Find me dinner” or “How did I sleep last night?”

How it works

Soma is a two-app pipeline:

Soma for iPhone reads from HealthKit and Core Location in the background using iOS observer queries and significant-change location monitoring. Data is written to a CloudKit private database zone in your Apple ID.
Soma Companion for Mac reads from the same CloudKit zone via your Mac’s iCloud sign-in. It indexes the data into a local SQLite store and exposes the data through a local MCP server on your loopback interface. Nothing leaves your machine.
Your AI agent connects to the local MCP server and makes tool calls against it. Responses return typed, structured data the agent can reason over.

Connecting agents

Soma speaks standard MCP over stdio and HTTP. Any MCP-compatible client works.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "soma": {
      "command": "soma-companion",
      "args": ["mcp"]
    }
  }
}

Cursor

Add Soma to ~/.cursor/mcp.json using the same shape as Claude Desktop.

OpenClaw / Hermes

Both clients auto-discover local MCP servers. Soma Companion advertises itself once the menubar app is running; no config change required.

ChatGPT

ChatGPT supports MCP through the remote MCP bridge or desktop plugin. Point the bridge at http://localhost:8741.

MCP tool reference

Every tool returns structured JSON. Time ranges accept either a since / until ISO-8601 pair or a shorthand like last_24h, last_7d.

Health tools

Tool	Purpose	Returns
query_heart_rate	Current and recent heart rate readings	{ bpm, timestamp, source }[]
query_hrv	Heart rate variability over a range	{ ms, timestamp, average_7d }[]
query_sleep	Sleep stages and duration for a night	{ date, score, stages, bedtime, wake }
query_steps	Step count aggregated by interval	{ interval, count, start, end }
query_workouts	Workout history with type and intensity	{ type, duration_min, avg_hr, max_hr, route? }[]
query_body_metrics	Weight, body fat percentage, BMI	{ weight_kg, bf_pct?, bmi?, timestamp }[]

Location tools

Tool	Purpose	Returns
query_current_location	Current GPS coordinates, speed, altitude	{ lat, lon, speed, altitude, heading, timestamp }
query_location_history	Location samples for a time range	{ lat, lon, timestamp }[]
query_geofence_events	Geofence enter/exit events for named places	{ place, event, timestamp }[]
query_activity_type	Current Core Motion activity type	walking \| running \| driving \| stationary \| unknown

Example queries

Once Soma is connected, your agent can chain tool calls to answer contextual questions without you providing context.

Prompt

“How’s my recovery looking this week?”

Tool calls

query_hrv(range: last_7d)
query_sleep(range: last_7d)
query_workouts(range: last_7d)

Prompt

“Find me a coffee shop nearby.”

Tool calls

query_current_location()
query_activity_type()
// agent combines with its own search tool

Prompt

“Did I actually run yesterday, or did I just walk around a lot?”

Tool calls

query_workouts(range: last_24h)
query_steps(interval: hour, range: last_24h)

Writing skills

A Soma skill is any program that chains Soma’s tool calls into a higher-level behavior. Skills can be:

A system prompt that tells an agent when and how to call Soma’s tools.
A scheduled script that calls the MCP server on a cron (e.g. Welcome Home).
A composed MCP server that wraps Soma’s raw tools into higher-level ones (e.g. recovery_report()).

Starter templates are open-source:

View skill templates on GitHub →

Privacy model

Soma Companion’s MCP server binds to 127.0.0.1 only. Remote connections are refused at the socket level. Data that flows out of Soma is data your agent explicitly decides to send elsewhere — for example, if Claude Desktop is configured to use Anthropic’s hosted API, tool call results become part of the prompt Claude sends back to its API.

See the privacy policy for the full architecture.

Troubleshooting

The agent says Soma isn’t responding.: Check that Soma Companion is running (menubar icon is active). Restart the agent after changing MCP config.
Health data looks stale.: iOS throttles background sync aggressively. Open the Soma iPhone app briefly to trigger a fresh sync. Location data syncs in near-real-time; health metrics sync every 15–45 minutes via Background App Refresh.
I don’t see HRV or sleep stages.: HRV, sleep stages, and blood oxygen require an Apple Watch. Soma gracefully returns null for missing signals rather than failing the tool call.
Can I run Soma on a different port?: Yes. Edit ~/Library/Application Support/Soma/config.json and restart the menubar app.

← Back to home