MCP Setup Guide

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to securely access external data sources. With Historicle's MCP server, you can give Claude Desktop (or other MCP-compatible assistants) access to your journal entries while keeping your data on your own machine.

This enables powerful use cases like:

• Asking Claude about your journal with its full reasoning capabilities
• Getting help writing or reflecting based on past entries
• Cross-referencing your journal with other data sources
• Building custom workflows that include your journal data

Prerequisites

• Historicle Pro (MCP Server feature)
• Claude Desktop installed on your Mac
• Your semantic search embedding model downloaded (for search functionality)

Setup Instructions

Step 1: Find the Historicle Binary Path

The Historicle app contains the MCP server. You'll need the path to the binary. Typically this is:

/Applications/Historicle.app/Contents/MacOS/Historicle

Step 2: Configure Claude Desktop

Open Claude Desktop's configuration file. You can find it at:

~/Library/Application Support/Claude/claude_desktop_config.json

If the file doesn't exist, create it. Add the following configuration:

{
  "mcpServers": {
    "historicle": {
      "command": "/Applications/Historicle.app/Contents/MacOS/Historicle",
      "args": ["--mcp-stdio"]
    }
  }
}

If you already have other MCP servers configured, add the "historicle" entry to your existing "mcpServers" object.

Step 3: Restart Claude Desktop

Quit Claude Desktop completely and reopen it. The MCP server connection will be established automatically.

Step 4: Verify Connection

In Claude Desktop, you should see Historicle listed as an available tool. Try asking Claude something like "Search my Historicle journal for entries about travel" to verify the connection is working.

Available Tools

Once connected, Claude can use these tools to interact with your journal:

• search_entries - Semantic search across all entries
• read_entry - Read the full content of a specific entry
• get_recent_entries - Get your most recent entries
• get_entries_by_date - Query entries within a date range
• get_entries_by_person - Find entries mentioning a specific person
• get_entries_by_interest - Find entries with a specific hashtag
• list_people - List all people you've mentioned
• list_interests - List all your interests/hashtags
• create_entry - Create a new journal entry (requires explicit permission)

Privacy & Security

Your journal data remains on your local machine at all times until you query it through MCP. When Claude accesses your journal:

• The MCP server runs locally on your computer
• Only the data relevant to your query is sent to Claude
• You control exactly what Claude can access through tool permissions
• MCP requires manual setup - it is never enabled automatically

This is different from uploading your entire journal to a cloud service - data only leaves your machine when you explicitly query it. However, once data is sent to an external AI service, it is subject to that service's data handling policies.

Troubleshooting

Claude doesn't show Historicle tools

• Verify the path to Historicle is correct in your config
• Make sure you've restarted Claude Desktop after adding the config
• Check that Historicle Pro is activated
• Try running the command manually in Terminal to check for errors:

  /Applications/Historicle.app/Contents/MacOS/Historicle --mcp-stdio

Search returns no results

• Ensure you have the embedding model downloaded in Historicle Settings
• Make sure you've generated embeddings for your entries (Settings > Journal Search)
• Verify you have entries in your journal

Connection times out

• The first query may take longer while the embedding model loads
• Ensure Historicle isn't already running - the MCP server needs exclusive database access

Example Queries

Here are some things you can ask Claude once connected:

• "Search my journal for entries about my career goals"
• "What have I written about @Sarah in the past year?"
• "Find entries from December 2024"
• "What are my most common interests in my journal?"
• "Read my most recent entry and help me reflect on it"
• "Based on my journal, what activities make me happiest?"

Need Help?

If you're having trouble with MCP setup, check our troubleshooting guide or contact support.