KSJ

You can privately connect your handwritten journal to an AI assistant using a local MCP server. This enables fast searching, idea connections, open questions tracking, and easy export — all processed on your machine without cloud access.

How to use

After you set up the MCP server, you interact with your AI assistant as you normally would, but with direct access to your journal content. You can upload journal photos, search across your notes, reveal connections between ideas, surface your open questions and insights, and export your knowledge base as Markdown or JSON. Use natural language prompts to guide your AI, such as asking it to find ideas about a topic, show related notes, or export a filtered subset of your captures.

How to install

Follow these concrete steps to install and run the MCP server locally.

Step 1 — Install an MCP-compatible AI client
- Claude Desktop is the recommended starting point and is free at claude.ai/download
- For other MCP clients, follow their documentation to register a local MCP server and then use the config in Step 3

Step 2 — Install Tesseract OCR
- Tesseract reads the text from your journal photos and must be installed separately

Platform specific commands:

Windows
- Download the installer from UB-Mannheim/tesseract and check "Add to PATH" during install

macOS
- `brew install tesseract`

Linux
- `sudo apt install tesseract-ocr`

After installation, restart your terminal and AI client to pick up the updated PATH

Step 3 — Register the server
Claude Desktop config file location:

Windows
- `%APPDATA%\Claude\claude_desktop_config.json`

macOS/Linux
- `~/.config/claude/claude_desktop_config.json`

Add the following block to the config (copy exactly — no path to set):

```json
{
  "mcpServers": {
    "ksj": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ChavezAILabs/ksj-mcp",
        "ksj-mcp"
      ]
    }
  }
}

uvx downloads and runs the server automatically — nothing else to install. Save and restart your AI client. You should see ksj listed in the tools/integrations panel.

## Additional setup notes

The MCP server for this project is designed to run locally and is configured to load via the UVX runner from the Git repository. Ensure your OCR is functioning, then connect your MCP-compatible AI client to the `ksj` server to begin using the tools and features described.

## Troubleshooting

If you encounter OCR or template issues, verify Tesseract is installed and accessible from your PATH. If the server does not appear in your client’s tools panel, confirm that `uv` is installed (`uv --version`) and that the config JSON is correct and saved in the proper location for your platform. On Windows, ensure the file path uses forward slashes or escaped backslashes in JSON.

## Data location

All captures and images are stored locally on your machine in the following locations:
- ks j-mcp/data/captures.db (SQLite database)
- ksj-mcp/data/images/ (image copies, if saved)
The `data/` directory is ignored by version control and never leaves your machine.

## License

MIT — free to use, modify, and share.

## Available tools

### upload\_capture

OCR a journal photo, parse the template, store it, highlight strongest connection

### bulk\_upload

Process a whole folder of photos at once

### search\_captures

Full-text search with optional tag and date filters

### find\_connections

Show tag-overlap and `@`-reference connections for a capture

### get\_stats

Overview: counts, top tags, open questions, insights, date range

### export\_captures

Dump your knowledge base as Markdown or JSON

### suggest\_synthesis

Find RC topic clusters ready to become a SYN entry

### export\_study\_deck

Export `?` questions as a portable CSV study deck (Anki, Quizlet, Notion, etc.)

### journal\_health

KPI dashboard + coaching: velocity, synthesis ratio, review cadence, open questions