everlog-mcp

A read-only MCP server for the Everlog journal app on macOS. It lets an MCP client (Claude Code, Claude Desktop, ...) search and read your journal entries, tags, photos and statistics straight from Everlog's local database. It never writes to or copies Everlog's data.

Tools

Dates are Everlog's own local days (America/Denver), YYYY-MM-DD.

Related MCP server: message-container

Install / run

Requires macOS, Python 3.13 and uv.

uv run everlog-mcp          # speaks MCP over stdio
uv run pytest -q            # tests (synthetic data only)

Configuration (environment variable):

• EVERLOG_DIR - Everlog data directory. Default: ~/Library/Group Containers/group.hummingbird.

Register with a client (examples; not done for you)

claude mcp add everlog -- uv --directory /path/to/Everlog-mcp run everlog-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "everlog": {
      "command": "uv",
      "args": ["--directory", "/path/to/Everlog-mcp", "run", "everlog-mcp"]
    }
  }
}

macOS permission

Everlog's data lives in a Group Container. The app that launches the server (Claude Desktop, your terminal, ...) may need Full Disk Access or the "access data from other apps" permission in System Settings > Privacy & Security. If the database cannot be opened, tools return an error explaining this.

Privacy

Whatever the tools return (entry text, summaries, photos, locations) is sent to your MCP client's model provider as part of the conversation. Only connect this server to clients and models you are comfortable sharing your journal with. The server itself makes no network connections and logs only counts/timings to stderr.

How it works / data-format notes

• Everlog stores Core Data SQLite files Hummingbird.sqlite (entries, journals, tags, places, weather, AI summaries) and AttachmentData.sqlite (attachment bytes), in WAL mode. Both are opened with mode=ro (never immutable, so recent WAL content is visible).

• At first use the server builds an in-memory SQLite FTS5 index (porter stemming) of entry text plus audio transcriptions, and re-checks PRAGMA data_version before every call; if Everlog committed changes, the index is rebuilt (about a second for ~10k entries).

• ZTEXT is the real markdown (ZCONTENT is a placeholder). Columns named ZENCRYPTED* actually hold plaintext and are preferred over their unprefixed twins. Trashed entries are excluded.

• Timestamps are Core Data epoch (Unix + 978307200). Day filtering uses ZYEARMONTHDAYID (Everlog's own America/Denver day bucket). Coordinates of 0/0 mean "none".

• Attachments are referenced in text as ![attachment](<32-hex id>). Blob bytes in ZATTACHMENTDATA.ZDATA start with 0x01 (inline bytes) or 0x02 (ASCII UUID of a file under .AttachmentData_SUPPORT/_EXTERNAL_DATA/). When several rows share an identifier the largest payload is used.

• Images are converted to JPEG (quality 80, longest side <= 1568 px by default) with macOS /usr/bin/sips, which also handles HEIC.

• Weather: temperature in deg C, pressure converted from Pa to hPa, humidity 0 means "no data".

License

MIT