apple-journal-mcp
Allows reading Apple Journal entries on macOS, including recent entries, date-range listings, search, entry details with photos, locations, links, audio transcripts, journal lists, and journal statistics.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@apple-journal-mcp show me what I journaled about over the past week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
apple-journal-mcp
A read-only MCP server that lets Claude (or any MCP client) read your Apple Journal entries on macOS: recent entries, date ranges, search, photos, locations, links, and audio transcripts.
It is a thin wrapper around journal-cli, which reads Journal's local data store through a temporary snapshot, so the live store is never opened.
Tools
Tool | What it does |
| Last N days including today, full text. |
| Date range, full text. |
| One entry with photos, locations, links, audio transcripts |
| Case-insensitive substring search over titles and text |
| Journals with entry counts |
| Entry, word, attachment counts and a per-year histogram |
| Checks the install and Full Disk Access |
Entry JSON has id, uuid, date (YYYY-MM-DD HH:MM:SS, local time),
title, text, chars, bookmarked, draft and synced. show_entry
adds assets, where each asset has a type (photo, video, livePhoto,
multiPinMap, link, audio, drawing, …), files[].path, and type-specific
fields: places[] for locations, url/link_title for links, and
duration/transcript for audio.
Read-only by design
A journal is yours to write. This server lets Claude read, find and reflect on what you wrote, and it never writes for you. The guards below keep it that way:
The server only runs the read commands
list,show,search,journals,statsanddoctor. It refuses anything else, and refuses--live,--accept-risk,--forceand--hardeven on read commands.Every tool carries the MCP
readOnlyHintannotation, so clients can tell that it does not modify anything.Inputs are validated before journal-cli sees them. Dates must be real
YYYY-MM-DDdates, limits must be positive, and search queries cannot start with--(journal-cli would read those as options).
Related MCP server: message-container
Requirements
A Mac where Apple Journal is set up, so its entries are in this Mac's local store
journal-cli:
brew install omarshahine/tap/journal-cliuv:
brew install uv
Install
git clone https://github.com/Ls-Dai/apple-journal-mcp.git
cd apple-journal-mcp
uv syncFind the absolute paths you'll need for the config:
which uv journal-cli # e.g. /opt/homebrew/bin/uv, /opt/homebrew/bin/journal-cli
pwd # the repo pathSmoke test from Terminal (Terminal needs Full Disk Access for this step):
uv run python -c "from apple_journal_mcp import server; print(server.doctor())"You should see Read N entries. All good.
Configure
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add
the server under mcpServers, using the absolute paths from above:
{
"mcpServers": {
"apple-journal": {
"command": "/opt/homebrew/bin/uv",
"args": ["run", "--directory", "/Users/you/Development/apple-journal-mcp", "apple-journal-mcp"],
"env": { "JOURNAL_CLI": "/opt/homebrew/bin/journal-cli" }
}
}
}Then:
Grant Full Disk Access to Claude.app in System Settings → Privacy & Security → Full Disk Access. macOS checks the app that launched the process, so granting it to Terminal is not enough.
Quit Claude completely (⌘Q) and reopen it.
Ask Claude to run the
doctortool.
Claude Desktop launches servers with a minimal PATH, which is why the config
uses absolute paths. Without JOURNAL_CLI, the server also looks in
/opt/homebrew/bin, /usr/local/bin, ~/.homebrew/bin, ~/.npm-global/bin
and ~/.local/bin.
Claude Code
claude mcp add apple-journal --scope user \
-e JOURNAL_CLI=/opt/homebrew/bin/journal-cli \
-- uv run --directory /Users/you/Development/apple-journal-mcp apple-journal-mcpClaude Code runs inside your terminal, so the terminal app (Terminal, iTerm2,
Ghostty, …) needs Full Disk Access. Check with claude mcp list, or /mcp
inside a session.
Without cloning
uv can run the server straight from GitHub:
"apple-journal": {
"command": "/opt/homebrew/bin/uvx",
"args": ["--from", "git+https://github.com/Ls-Dai/apple-journal-mcp", "apple-journal-mcp"],
"env": { "JOURNAL_CLI": "/opt/homebrew/bin/journal-cli" }
}Other MCP clients
This is a standard stdio server. The command is uv, the args are
run --directory /path/to/apple-journal-mcp apple-journal-mcp, and
JOURNAL_CLI is optional. Whatever app launches it needs Full Disk Access.
Environment variables
Variable | Purpose |
| Absolute path to |
| Read a different |
Agent skill (optional)
skills/apple-journal/SKILL.md teaches
Claude how to use these tools well: picking date ranges, searching
effectively, reading assets, and handling journal content with care.
Claude Code:
ln -s "$PWD/skills/apple-journal" ~/.claude/skills/apple-journalClaude Desktop / claude.ai: zip the
skills/apple-journalfolder and upload it as a custom skill in Claude's settings.
Troubleshooting
Symptom | Fix |
| Set |
| Grant Full Disk Access to the app that launches the server (Claude.app or your terminal), then quit and reopen it |
Server missing in Claude Desktop | Check |
Fewer entries than expected | Dates are local time. Make sure Journal has synced to this Mac; entries with no title and no text are skipped |
Interactive testing |
|
Development
main only changes through pull requests: work on a branch, then open a PR.
Git hooks in .githooks/ refuse commits on main and pushes to it. Enable them
once per clone:
git config core.hooksPath .githooksuv sync # installs pytest and ruff too
uv run pytest # unit tests; never call a real journal-cli
uv run ruff check . && uv run ruff format --check .Integration tests run the real journal-cli against a synthetic store built by
the CLI repo's tests/make-fixture.sh. That store contains no personal data,
and your real journal is never opened:
JOURNAL_CLI_SRC=~/Development/apple-journal-cli uv run pytest -m integrationSee CLAUDE.md for architecture notes and journal-cli quirks.
Credits
journal-cli by Omar Shahine does the hard part of decoding Journal's private Core Data store.
License
Available Tools
7 toolsdoctorARead-only
Check that journal-cli is installed and can read the Journal store.
Inputs: no named parameters. Returns: result
journal_statsCRead-only
Entry, word, attachment and per-year counts (plain text).
Inputs: no named parameters. Returns: result
list_entriesBRead-only
Entries in a date range with full text, as JSON.
Dates are YYYY-MM-DD in local time, and both ends are inclusive.
Inputs: since (required), limit, until. Returns: result
list_journalsCRead-only
All journals with entry counts, as JSON.
Inputs: no named parameters. Returns: result
recent_entriesARead-only
Entries from the last N days (inclusive of today), with full text, as JSON.
days=1 is today only; days=7 is today plus the six days before it.
Inputs: days, limit. Returns: result
search_entriesBRead-only
Case-insensitive substring search over entry titles and text, as JSON.
Inputs: query (required), limit. Returns: result
show_entryBRead-only
One entry with its assets: photos, locations, links, audio transcripts.
Inputs: entry_id (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
recent_entries and list_entries overlap because both return full-text entries over a date window; descriptions distinguish them, but an agent may still deliberate between them. Other tools are clearly distinct: show_entry for assets, search_entries for text search, list_journals/journal_stats for metadata, and doctor for setup.
All names use snake_case, and most are verb_noun (list_entries, show_entry, search_entries, list_journals). recent_entries and journal_stats are noun phrases, and doctor is a bare noun, but the pattern remains readable.
Seven tools is well-scoped for a focused journal-reading server. Each tool targets a distinct retrieval or diagnostic task without obvious filler.
The surface covers recent/range listing, single-entry details with assets, search, journal listing, stats, and a health check. As a read-only journal access toolset it is solid, though entry listing lacks a journal filter and there is no export or write operation (likely intentional).
Maintenance
Related MCP Connectors
Read, search and manage iCloud Mail, Calendar and Contacts from Claude and other MCP clients.
Private journal MCP server to search, analyze, and create Dabble Me entries securely via OAuth.
Handwritten iPad journal your AI can read and write tasks back to, over MCP.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceRead-only MCP server for Day One journal on macOS, enabling search and browsing of entries, photos, and metadata.2-
- FlicenseNot gradedqualityCmaintenanceEnables AI clients to read and search macOS Messages history through a read-only MCP interface.-
- AlicenseAqualityCmaintenanceLets MCP clients search iMessages, read Apple Notes including checklist state, and look up Contacts on macOS.12MIT
- AlicenseNot gradedqualityCmaintenanceEnables read-only access to the local Apple Calendar on macOS through an MCP client, allowing retrieval of today's events, events for a specific date, or events in a date range. It supports optional calendar filtering and keeps calendar data local.1MIT