Photon iMessage MCP

A separate MCP server for Photon Advanced iMessage features. It does not modify or replace Hermes' native Photon bridge. Version 0.1.0 focuses on shared Find My locations because those are not part of Spectrum's ordinary message stream.

The server reuses the Photon project already connected to Hermes. It exchanges the project ID and secret for short-lived Advanced iMessage credentials, selects the shared or dedicated route, and refreshes credentials without another login.

Tools

• photon_location_list — list allowed shared locations

• photon_location_get — fetch one allowed location

• photon_location_request — send a visible Find My request card

• photon_location_watch_start / photon_location_watch_stop — control the live gRPC location stream

• photon_location_watch_status — inspect watcher health

• photon_location_latest — read the last in-memory live update

Locations are never persisted or logged. PHOTON_ALLOWED_ADDRESSES is required and enforced inside the service. Visible requests are disabled unless PHOTON_ALLOW_MUTATIONS=true, and the tool call must also include confirm=true.

Related MCP server: iMessage MCP Server

Authentication

This server uses Photon's current @photon-ai/advanced-imessage gRPC SDK. The recommended configuration reuses the project credentials already held by the Hermes Photon bridge:

PHOTON_PROJECT_ID=11111111-1111-4111-8111-111111111111
PHOTON_PROJECT_SECRET=replace-at-runtime
PHOTON_ALLOWED_ADDRESSES=+14155550123
PHOTON_LOCATION_STALE_AFTER_SECONDS=300
PHOTON_ALLOW_MUTATIONS=false

For a dedicated project with multiple lines, set PHOTON_IMESSAGE_PHONE to the line that should own the MCP connection. Explicit endpoint/token configuration remains available for self-hosted Advanced iMessage servers.

Install into Hermes

Clone a pinned release into Hermes' persistent data volume and run the included installer from inside the Hermes container:

mkdir -p /opt/data/mcps
git clone --depth 1 --branch v0.1.0 \
  https://github.com/nathanielangafor/photon-mcp.git \
  /opt/data/mcps/photon-mcp
cd /opt/data/mcps/photon-mcp
./install-hermes.sh

The installer:

• confirms the existing Photon variables are present without printing them;

• builds pinned dependencies from package-lock.json;

• references the existing secrets in config.yaml instead of copying values;

• derives the MCP location allowlist from PHOTON_ALLOWED_USERS;

• preserves an existing MCP tool filter; and

• enables the server with mutations disabled.

It is safe to run the installer again from the same checkout. Start a new Hermes session after installation so the new MCP tools are discovered.

Build and test

Requires Node.js 20 or later.

npm ci
npm run check
npm test
npm run build

Run the MCP server over stdio:

npm start

The service writes MCP protocol frames only to stdout. Operational messages go to stderr, and Photon payloads and credentials are not logged.

Hermes configuration

Build the server, place this directory somewhere readable by the Hermes container, and add the following to ~/.hermes/config.yaml:

mcp_servers:
  photon-imessage:
    command: node
    args:
      - /opt/photon-mcp/dist/index.js
    env:
      PHOTON_PROJECT_ID: "${PHOTON_PROJECT_ID}"
      PHOTON_PROJECT_SECRET: "${PHOTON_PROJECT_SECRET}"
      PHOTON_ALLOWED_ADDRESSES: "${PHOTON_ALLOWED_USERS}"
      PHOTON_LOCATION_STALE_AFTER_SECONDS: "300"
      PHOTON_ALLOW_MUTATIONS: "false"

Hermes intentionally passes only configured environment variables to stdio MCP children. Do not commit the token or place it directly in this repository.

Current limitation

The live watcher is process-local and does not persist coordinates. A Hermes or MCP restart stops the watcher; call photon_location_watch_start again. Find My availability on Photon shared-pool lines still needs a live read-only probe.