benlen10/dayone-mcp

Day One MCP Server

A read-only Model Context Protocol (MCP) server for Day One journal on macOS. Access and search your Day One entries directly from Claude Desktop.

Features

• Unified search - Find entries with flexible filters (text, tags, starred, media, location, device, dates)
• View photos directly - Claude can see and analyze photos from your journal entries via MCP resources
• Media attachments - Access photos, videos, audio, and PDFs with full metadata
• Lazy loading - Efficient performance with include_tags and include_attachments flags
• List journals - View all journals with statistics
• Browse recent - Simply search with no filters
• "On This Day" - Use date filters to view historical entries

Prerequisites

• macOS with Day One app installed
• Python 3.11+
• uv package manager - Install from astral.sh

Installation

1. Install uv (if not already installed)

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone and setup

git clone <repository-url>
cd dayone-mcp
uv sync

3. Configure Claude Desktop

Add to your Claude Desktop config at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "dayone": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/dayone-mcp",
        "run",
        "python",
        "-m",
        "dayone_mcp.server"
      ]
    }
  }
}

Important: Replace /ABSOLUTE/PATH/TO/dayone-mcp with your actual installation path.

4. Restart Claude Desktop

After updating the configuration, restart Claude Desktop to load the MCP server.

Usage

Once configured, you can interact with Day One through natural language:

Example Queries

• "Show me my recent journal entries" - Browse recent (no filters)
• "Search my journal for entries about vacation" - Text search
• "Find starred entries tagged work from last month" - Multi-filter search
• "Show me all entries with photos from my iPhone" - Media + device filter
• "What did I write on October 31st in past years?" - Date filter for "On This Day"
• "List my Day One journals" - View all journals with stats

Available Tools

Just 2 simple tools:

1. search_entries

One powerful tool for all entry operations - search, browse, and filter.

Returns FULL entry text and all metadata.

All parameters are optional - use none for browsing, use filters to narrow results:

• text - Text to search for in entry content
• tags - List of tags (entry must have ALL specified tags)
• starred - Filter by starred status (true/false)
• has_photos - Filter entries with photo attachments
• has_videos - Filter entries with video attachments
• has_audio - Filter entries with audio recordings
• has_location - Filter entries with location data
• creation_device - Device type ("iPhone", "MacBook Pro", "iPad", "Apple Watch")
• date_from - Start date (YYYY-MM-DD)
• date_to - End date (YYYY-MM-DD)
• journal - Journal name filter
• limit - Number of results (1-50, default: 20)
• include_tags - Include tag data in results (default: false, set to true only if needed for performance)
• include_attachments - Include attachment/media resources in results (default: false, set to true when you want to view photos/videos/audio)

All filters use AND logic - results must match all criteria.

Examples:

Browse recent: search_entries(limit=10)
Text search: search_entries(text="vacation")
Starred + photos: search_entries(starred=true, has_photos=true)
With attachments: search_entries(has_photos=true, include_attachments=true)
With tags: search_entries(text="vacation", include_tags=true)
"On This Day": search_entries(date_from="2020-10-31", date_to="2025-10-31")
Multi-filter: search_entries(tags=["work"], creation_device="iPhone", date_from="2025-01-01", include_tags=true)

2. list_journals

List all Day One journals with statistics.

Returns:

• Journal names
• Entry counts per journal
• Last entry date for each journal

Database Location

The server automatically connects to Day One's database at:

~/Library/Group Containers/5U8NS4GX82.dayoneapp2/Data/Documents/DayOne.sqlite

Make sure Day One has been opened at least once to create the database.

Troubleshooting

Database not found

• Ensure Day One is installed and has been opened at least once
• The database is created when you first launch Day One

Permission issues

• Day One database is read-only from this server
• No write operations are performed

Claude Desktop connection issues

• Verify the absolute path in claude_desktop_config.json
• Check Claude Desktop logs for errors
• Restart Claude Desktop after configuration changes

Development

# Install dependencies
uv sync

# Run server directly (for testing)
uv run python -m dayone_mcp.server

# Run comprehensive test suite
uv run python tests/test_all.py

Test Coverage

The test suite (tests/test_all.py) validates:

1. Database connection and initialization
2. Basic operations (read/search)
3. Text extraction from rich text JSON and markdown
4. Entry formatting (preview vs full text)
5. Advanced search filters (text, starred, media, location, dates)
6. Lazy loading and performance (include_tags, include_attachments)
7. Get entry by UUID (for resource retrieval)
8. Attachment file verification
9. Display integration with resource URIs

License

MIT

Acknowledgments

Built with the Model Context Protocol by Anthropic.