soma-mcp
MCP server that exposes Soma's local Mac SQLite sensor replica to AI agents.
Reads from a local SQLite replica maintained by the Soma Mac app. Designed for use with any MCP-compatible agent (Claude, ChatGPT, Cursor, etc.).
In the App Store-safe build, HealthKit-derived rows are not synced through CloudKit, so health tools may return empty or stale data unless the local replica was populated by a future compliant transport. Location and activity tools continue to read replicated Mac data.
If Soma Mac has Agent Access turned off, every MCP tool returns a
permission error with instructions to re-enable access in the Mac app.
The local SQLite replica may still exist and continue syncing; the
toggle only controls whether soma-mcp is allowed to serve it.
Consumer Setup
For end users, the Soma Mac app generates the correct MCP configuration automatically from the menu bar.
Until soma-mcp 0.2.1 is published on PyPI, use a local checkout with uvx --from <path-to-soma-mcp> soma-mcp. Do not use unpinned uvx soma-mcp; PyPI may resolve an older package.
Development Quick Start
cd soma-mcp
uv run soma-mcp --db ~/.soma/sensors.db
Agent Configuration
The Soma Mac app generates the correct config for your machine — open the menu bar and click Copy Agent Config. Manual setup is below.
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"soma": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "/path/to/Soma/soma-mcp", "soma-mcp", "--db", "~/.soma/sensors.db"]
}
}
}
Claude Code
Use the CLI (recommended):
claude mcp add --transport stdio --scope user soma -- uvx --from /path/to/Soma/soma-mcp soma-mcp --db ~/.soma/sensors.db
Or edit ~/.claude.json (user scope) / .mcp.json (project scope) with the same JSON shape as Claude Desktop above.
Cursor
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):
{
"mcpServers": {
"soma": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "/path/to/Soma/soma-mcp", "soma-mcp", "--db", "~/.soma/sensors.db"]
}
}
}
VS Code / GitHub Copilot
Add to .vscode/mcp.json. Note the root key is servers, not mcpServers:
{
"servers": {
"soma": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "/path/to/Soma/soma-mcp", "soma-mcp", "--db", "~/.soma/sensors.db"]
}
}
}
Tools are available in Copilot Agent mode (VS Code 1.99+).
Codex CLI / Codex IDE
Codex shares config between the CLI and the IDE extension via ~/.codex/config.toml. Add:
[mcp_servers.soma]
command = "uvx"
args = ["--from", "/path/to/Soma/soma-mcp", "soma-mcp", "--db", "~/.soma/sensors.db"]
Or use the CLI:
codex mcp add soma --command uvx --arg --from --arg /path/to/Soma/soma-mcp --arg soma-mcp --arg --db --arg ~/.soma/sensors.db
OpenAI Agents SDK (Python)
The Agents SDK supports stdio MCP servers natively. Wire uvx --from /path/to/Soma/soma-mcp soma-mcp --db ~/.soma/sensors.db in via the SDK's MCPServerStdio class.
ChatGPT (consumer)
ChatGPT's Developer Mode supports MCP but requires remote HTTPS-hosted servers (Streamable HTTP / SSE) — stdio is not supported. Soma is a local-only product by design, so direct ChatGPT integration would require a stdio→HTTP bridge (e.g. mcp-proxy) plus a tunnel (Cloudflare Tunnel, ngrok). This isn't a natively supported flow.
Any other MCP client
The server uses stdio transport. Spawn uvx --from <path-to-soma-mcp> soma-mcp --db <path> as a subprocess.
Tools
| Tool | Description |
|---|---|
get_user_location() |
Current GPS coordinates, address, and freshness metadata |
get_location_history(since?, limit?) |
Location time-series, newest first |
get_health_summary() |
Latest sample metrics + current activity + daily snapshots |
get_health_metric(metric, since?, limit?) |
Metric history with metric-aware routing |
get_health_metrics_list() |
Available metrics inventory with latest values |
get_user_activity() |
Current physical activity (stationary, walking, running, etc.) |
get_daily_summary(date?) |
Daily health rollup with cumulative and aggregate stats |
get_workouts(since?, limit?) |
Workout session history with type, duration, distance, calories |
query_sensor_data(sql, limit?) |
Read-only SQL against the local replica |
Health Metrics (50 HealthKit metrics + activity + workouts)
Hourly stats (17): steps, active_calories, basal_calories, distance_walking/cycling/swimming, workout_minutes, flights_climbed, dietary metrics (energy, water, caffeine, protein, carbs, fat, fiber, sugar, sodium)
Daily snapshots (2): stand_hours, sleep_duration
Sample events (20): heart_rate, resting_heart_rate, walking_heart_rate_avg, blood_oxygen, respiratory_rate, body composition (mass, fat %, BMI, lean mass, height, waist), hrv, vo2_max, body/wrist temperature, blood pressure, blood_glucose, environmental_audio, walking_steadiness
Category events (11): mindful_session, cardiac events (low/high HR, irregular rhythm), symptoms (headache, fatigue, nausea), reproductive health (menstrual_flow, cervical_mucus, ovulation_test, sexual_activity)
Activity: user_activity (stationary, walking, running, automotive, cycling, unknown)
Workouts: Full HKWorkout records with type, duration, distance, energy
Freshness Metadata
Every response includes freshness fields so agents can assess data recency:
recorded_at— when the sensor reading was takenupdated_at— when it was last applied to local SQLiteage_seconds— how old the reading isstale— boolean based on metric-specific thresholds
Requirements
- The Soma iOS app collecting sensor data on your iPhone
- The Soma Mac app replicating data to
~/.soma/sensors.db - Python 3.10+ (managed automatically by
uvx)
Changelog
0.2.1
Maintenance release with stricter MCP query parsing and compatibility fixes.
0.2.0
Response field names normalized to snake_case for consistency with SQLite column names and Python conventions:
ageSeconds→age_secondsactivityLabel→activity_labellatestMetrics→latest_metrics
Response fields are snake_case to match SQLite column names and Python conventions.
Added MCP tool annotations (readOnlyHint, idempotentHint) and server instructions for agent discovery. SQL validation rejects mutating statements and disallowed SQLite escape hatches before execution.
0.1.0
Initial release with all 8 MCP tools.
Development
cd soma-mcp
pip install -e .
soma-mcp --db ~/.soma/sensors.db
Metadata
Release files for soma-mcp 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| soma_mcp-0.2.1.tar.gz | 106.1 kB | Without provenance | Details for soma_mcp-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| soma_mcp-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for soma_mcp-0.2.1-py3-none-any.whl |
Total release size: 125.2 kB
Release files / soma_mcp-0.2.1.tar.gz
| Download URL | soma_mcp-0.2.1.tar.gz |
|---|---|
| Size | 106.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5c42766d939107144d47ef7f9003b567212997adce6ee4c48e622539074dbb31
|
|
BLAKE2b-256 checksum How to use checksums |
064429df969570b3d2c4a9a7ed36eefd943340314f47a5504cc4f0bf53d9925b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.27 {"installer":{"name":"uv","version":"0.9.27","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / soma_mcp-0.2.1-py3-none-any.whl
| Download URL | soma_mcp-0.2.1-py3-none-any.whl |
|---|---|
| Size | 19.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5cd413a412d8fe7288f647d0865332b0d41be7a518ce4684a4a6c4f2b78e9095
|
|
BLAKE2b-256 checksum How to use checksums |
4df86f863026ed24f078ad4c46dc1a890d022861335c76e9e15882f276bdd8d3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.27 {"installer":{"name":"uv","version":"0.9.27","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for soma-mcp 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.