Personal Context Bridge

A self-hosted MCP bridge for your own Apple, Canvas, Health, travel, and Obsidian context. Search encrypted archives from an MCP client, check sync freshness, and retrieve bounded records. Each person supplies their own accounts and devices.

This repository contains reusable code and fictional tests. It ships no personal archive, account credentials, installed app IDs, or maintainer deployment history.

Try it with fictional data

Use Python 3.11+ on Linux for the archive server. With uv:

git clone https://github.com/jeremydevv/personal-context-bridge.git
cd personal-context-bridge
uv venv --python 3.11
uv pip install -e '.[mcp,messages,images]'
.venv/bin/personal-context-setup --demo --iphone

The setup command creates a random 32-byte key, encrypted databases, private source templates, upload credentials, and mcp.json under ~/.local/share/personal-context-bridge/runtime. It refuses to overwrite an existing installation or put runtime state inside a source checkout. --iphone is optional; it creates empty Health/travel archives, not fictional health data.

Copy the generated mcpServers entries from that private mcp.json into your MCP client's configuration. The file already contains absolute paths to this installation's Python interpreter and private archive. Restart the client and ask it to search for fictional. The demo returns three clearly fictional Calendar, Reminder, and Notes records. Use a separate --root when setting up real collection, so demo records do not mix with your context.

For pip, replace the two uv commands with python3 -m venv .venv and .venv/bin/pip install -e '.[mcp,messages,images]'. On Ubuntu, install the matching python3-venv package if venv creation is unavailable. There is no published PyPI package yet; install from this repository.

Connections

Connect your sources

Follow setup for Mac-to-Linux collection, Canvas, iPhone receivers, Timeline imports, Obsidian, scheduling, and backups. MCP configuration examples show the separate source servers. For ChatGPT web, follow the private tunnel guide. The archive works while collection devices are asleep; check timestamps before assuming current data.

The Apple collectors need macOS. The archive/query service and iPhone receivers are tested on Linux. On macOS, the mcp extra uses sqlcipher3, requiring a working native SQLCipher build (for example Homebrew SQLCipher plus matching compiler flags). Windows is not supported by the current Unix lock/mount code. Image previews require the images extra and PDF text extraction requires pdftotext (poppler-utils on Ubuntu). Locked Notes, absent Messages attachments, and image-only PDFs may have no readable content.

Privacy and writes

Archives use SQLCipher; binary attachments use authenticated AES-GCM encryption. Keys and upload credentials are separate files created with mode 0600 in a private directory. Keep a secure recovery copy of the key: losing it loses access to your archive. Read privacy and retention before using real data.

The default MCP surfaces retrieve data. Refresh requests and Mail sending are opt-in. Obsidian writes require explicit server configuration and revision checks. Mail sending uses a separately configured sender/account and a worker with a five-minute cancellation window. Tool annotations and descriptions do not enforce human approval; configure your client to require approval for write operations.

Local storage does not mean the AI provider never sees your data: tool results are sent to the client/model you connect. Do not expose the receiver ports directly to the public internet. Supply an authenticated, encrypted network path for phone uploads; the receiver processes deliberately bind to loopback.

Development

uv pip install -e '.[mcp,messages,images,dev]'
.venv/bin/python -m unittest discover -s tests
.venv/bin/python -m unittest discover -s iphone/tests
.venv/bin/python iphone/tests/upstream_smoke_test.py
.venv/bin/python scripts/check_release.py
.venv/bin/python -m build

The Health HTTP smoke test uses synthetic upstream fixtures and temporary encrypted storage. Device permissions and live account access are user-specific and are not exercised by CI. See CONTRIBUTING.md.

Original bridge code is MIT licensed. Adapted PulsHealth components retain Apache-2.0 licensing; see NOTICE.