18-companion-apps
Companion apps and the local server
The Iris Mac app can run a small local web server that serves your library to other devices on your home network. This is how the iPhone & iPad companion app and the Apple TV app work — they talk to your Mac directly over the LAN.
There's also a tiny built‑in web UI and a Model Context Protocol (MCP) server for AI tools. Each is independent and can be enabled or disabled separately in Settings → Server.
Why a local server?
- Your library lives only on your Mac. Nothing is uploaded to the cloud.
- Your phone, iPad, and Apple TV need a way to ask the Mac for thumbnails, metadata, and full‑res files.
When the server is enabled, the Mac advertises itself on the local network, so companion apps can discover it automatically by name.
Enabling the server
- Open Iris → Settings (
⌘,). - Click the Server tab.
- Turn on Enable API Server.
The server starts immediately. Other devices on your network can now connect.
Approving a new device (pairing)
The first time a new device tries to connect, the Mac shows an approval prompt:
The prompt shows a 6‑digit code. The same code is displayed on the iPhone or Apple TV that's trying to pair. If the two codes match, click Allow.
Approved devices are remembered, so the next time the same device connects (e.g., when you re‑open the iPhone app), it goes straight through without prompting.
The companion apps
Iris for iPhone & iPad
An app for iOS that browses your library in a five‑tab layout: Library, Dates, Places, People, Settings. It streams thumbnails and full‑resolution media from your Mac. Read‑only — you can view, share, and explore, but adding chapters and naming people still happens on the Mac.
Iris for Apple TV
A tvOS app for browsing your library on the big screen. Includes a "Surprise Me" mode that picks a random photo and advances with a retro projector click.
The local website (experimental)
Toggling Enable Website in Settings → Server turns on a simple browser interface for your library at http://<your-mac>.local:8490 (or by IP). Use it from any browser on your local network — useful for guests on Wi‑Fi, or quick lookups from a Linux/Windows computer.
The website is read‑only, like the iOS app.
MCP (Model Context Protocol)
Toggling Enable MCP Server exposes your library to AI tools that speak Model Context Protocol — for example, Claude desktop apps can be configured to query your library directly.
Available tools include:
- Search your library
- Get items by person, location, chapter, or tag
- Fetch metadata for a specific item
- List people, locations, chapters
- Library statistics
All MCP access is read‑only.
Security and privacy
- The server only listens on your local network. It does not expose anything to the public internet.
- Every connection requires an approval from the Mac the first time. The 6‑digit code prevents random devices on your network from connecting silently.
- The server speaks plain HTTP — it relies on your LAN's perimeter for security. Don't enable the server on a network you don't trust.
- You can turn the server off at any time in Settings → Server.