The self-hosted mirror
A small server on hardware you own that keeps a complete, live copy of your Marrow data and answers agents while your phone is asleep, in a pocket, or on the other side of the world.
Setup for one app at a time is on its own page under connections.
All Marrow guides: MCP · Self-hosted mirror · Automations · Files · Support
What it is
A small open-source server you run on hardware you own: a Raspberry Pi, a NAS, an old laptop, a $5 VPS. Your phone pairs with it once by scanning a QR code, then pushes every change in the background, with the app closed. The server keeps a complete SQLite copy of your Marrow data and serves thirteen MCP tools for reading: the phone's seven, sleep_log and symptoms_and_mood, and four that answer in the app's own terms (daily_brief, baselines, what_changed, data_quality), so an agent can ask "how did I sleep this week" at 3 a.m. with your phone in a drawer. MIT licensed: github.com/MarrowHealth/marrow-mcp.
Install
One Python file, standard library only, Python 3.10 or newer:
pip install marrow-mcp marrow-server # or: python3 marrow_server.py
Or with Docker:
git clone https://github.com/MarrowHealth/marrow-mcp cd marrow-mcp docker compose up -d
On first start it prints a pairing URL and shows a QR code in any browser on your network.
Pair the phone
- Open the pairing URL on any screen near you.
- In Marrow: Export, Server MCP, Pair with a server, scan the code.
- Done. The phone starts pushing, and the Server page shows the last push time and how many records are waiting.
Pairing creates two tokens in the server's data directory: one the phone uses to push, one agents use to read. Delete a token file to rotate it.
Point an agent at it
claude mcp add --transport http marrow http://<server-ip>:8800/mcp \ --header "Authorization: Bearer <mcp token>"
Thirteen tools, all reads. The nine raw ones: health_summary, list_metrics, metric_daily, metric_samples, workouts, nutrition_log, strength_log, sleep_log, symptoms_and_mood. And four that start where the raw ones stop, scored against your own trailing normal with the same math the app's Home page uses: daily_brief (one day: each key metric with its value and the app's own phrase, food and water against your targets, last night's sleep, training done, flags worth mentioning), baselines (your own normal per metric, the latest value's z and the 90-day trend), what_changed (the last week against the four before it: what moved, how notable it is for you, sleep and bedtime shifts, streams that started or stopped) and data_quality (what is fresh, stale or missing, so an agent never mistakes a gap for a fact). Every read takes days back or from and to on the phone's calendar. The server also lists four prompts (how_am_i_doing, weekly_review, doctor_prep, log_from_text) and four resources for clients that show them. It carries twelve write tools too, listed once your phone allows them. From Marrow 1.5, turn on Allow AI write for your server in Connects, Your AIs and an AI can log meals, water, weight, workouts, sleep, symptoms, mood and targets through it, free. The server queues each entry and the phone applies it when Marrow opens or wakes, and every one can be undone. Setup for Claude Desktop, Cursor and others is on the MCP page. Only the URL changes.
Reaching it from outside your LAN
The server speaks plain HTTP and has no TLS of its own. Do not port-forward it raw. Put Tailscale on the box and the phone and use tailscale serve, or front it with Cloudflare Tunnel or any reverse proxy that terminates HTTPS. The pairing QR carries the address the server advertises: its own LAN address, or the one you give it with --url. Start it with the address you will actually use, for example marrow-server --url https://pi.your-tailnet.ts.net, then pair.
What lands on disk
- A SQLite database with every daily series, sample, diary entry and strength set, kept current by the phone's pushes.
- Every raw push staged as JSONL next to it, so the database can be rebuilt if you ever mangle it.
- Budget 50 to 150 MB per year of full-fidelity history.
Units: Health metrics arrive in their stored SI units with labels. Strength sets arrive in pounds with "unit": "lb" whatever the phone's display setting, so the mirror never mixes units. Point Grafana, DuckDB or a cron job straight at the database file.
Troubleshooting
Two tests from the computer your AI runs on tell you where the problem is. First, is the server up? This one needs no token:
curl http://<server-ip>:8800/health
It answers {"server": "marrow", "ok": true}. Then, does your agent's token work?
curl -i http://<server-ip>:8800/mcp \ -H "Authorization: Bearer <mcp token>" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
| What you get | What it means |
|---|---|
200 OK and a list of tools | The server works. Check the address, the token and the server type (HTTP) in your agent's config, then restart the agent. |
401 with bad bearer token | Wrong token. Agents use the mcp token, not the one the phone pairs with. See below. |
| Connection refused or a timeout | The server is not running, the port is wrong, or a firewall on the box blocks port 8800. With Docker, check the 8800:8800 port mapping. |
- Which token. The server prints the agents' token when it starts, on the line that begins
agents:. It is also in the.mcp-tokenfile in the data folder (./dataunless you passed--data,/datain Docker). The phone uses a different token, from.app-token. To change the agents' token, delete.mcp-token, restart the server and update every agent. - The pairing page says bad or missing token. Open the pair link exactly as the server printed it, with its
?token=part. - The pairing page shows text, not a QR code. The QR needs the optional
segnopackage:pip install "marrow-mcp[qr]". Or, in Marrow, choose Enter manually instead and type theurlandtokenfrom that text. - Pairing failed on the phone. The phone could not reach the address in the QR. Under Docker the server sees only the container's own address, so give it yours: add
--url http://<your-computer-ip>:8800to its command. Off your home Wi-Fi, use an HTTPS address fromtailscale serveor a tunnel. - Local Network access. To reach a server on your home network, Marrow needs Local Network access. iOS asks the first time you pair. If you said no, turn Marrow on in Settings, Privacy and Security, Local Network, then pair again with Marrow open.
- That QR code isn't a Marrow pairing code. The camera read another code. Scan the one on the server's pairing page.
- Old data, or Not delivering in Marrow. The phone cannot push to the server. The Server MCP page in Marrow shows the last push and how many records wait. Check the server is running, then open Marrow to send what is waiting. Background pushes run when iOS allows.
- This server needs an update before it can log. Update it with
pip install -U marrow-mcpand restart it. With Docker, rungit pullanddocker compose up -d --buildin the clone. - Entries from the AI do not show. Turn on Allow AI write for the server in Connects, Your AIs. The write tools appear on the server only after that. Each entry waits on the server and lands when Marrow next opens or wakes.
- The connection will not switch on. Free keeps 3 connections on at a time, Marrow Pro up to 20: AIs, servers and automations together. Sources never count.
When to choose this over the others
Choose the mirror when your agent needs the data while your phone is asleep or away, or when you want a queryable database rather than files. Choose the on-phone MCP server when your agent runs near the phone and you want nothing else to maintain. Choose automations when you already have a place data should land.