Note: MCP Server is a Historicle Pro feature. Upgrade to Pro to use this feature.

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. The source journal stays on your computer, but content returned by tools is shared with the connected assistant.

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

Use the app you installed. The binary name is lowercase historicle. The MCP process checks the App Store/TestFlight sandbox data directory first, then the standalone data directory. If you have multiple journals or installations, use --data-dir with the exact folder above the models folder opened from Settings → General → App Folders → Models.

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

Use get_life_context or get_journal_stats to understand the journal, then get_recent_entries, read_entry, or person, interest, date, goal, and emotion queries to explore it.

search_entries is available when the embedding service is loaded. The standard --mcp-stdio launch is read-only: write tools are not advertised or accepted. See the complete tool reference and availability notes.

Privacy & Security

Important Privacy Notice

When you use MCP to connect your journal to external AI services like Claude, journal data you query will be sent to that service. Historicle has no control over whether this data may be used for AI training by the external provider. Review the privacy policy of any AI service you connect to. This is an opt-in feature that requires manual configuration - your journal data is never shared unless you explicitly set up MCP.

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. Open the app and restore or validate your purchase if MCP reports an expired validation

Try running the command manually in Terminal to check for errors:

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

MCP writes logs to the app's logs directory rather than the JSON-RPC output stream. Use the log-directory action in Settings when reporting an error.

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
Historicle and MCP can run together. If the database is busy, allow an import or restore to finish, and confirm both processes use the intended data directory

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.

MCP Setup Guide