# LiveJournal MCP Server

Local MCP server for LiveJournal journals. It uses the legacy LiveJournal XML-RPC API to read entries, read comments, post to your own journal, and build a local SQLite cache for search.

## Features

- Read recent entries.
- Read one entry by `itemid`.
- Read entries for a specific date.
- Search recently fetched entries.
- Read entry comments with `LJ.XMLRPC.getcomments`.
- Create posts, with `dry_run: true` by default.
- Generate an `ljsession` for authenticated LiveJournal web endpoints.
- Cache entries in SQLite and search cached entries locally.

## Tools

- `check_login`
- `list_entries`
- `get_entries_for_date`
- `search_recent_entries`
- `get_entry`
- `sync_entries`
- `get_entry_comments`
- `create_post`
- `generate_session`
- `cache_recent_entries`
- `cache_entries_for_date`
- `cache_synced_entries`
- `cache_entry`
- `search_cached_entries`
- `list_cached_entries`
- `get_cached_entry`
- `cache_stats`
- `clear_cache`

## Requirements

- Python 3.10+
- A LiveJournal account
- An MCP-compatible client

SQLite is built into Python. No separate SQLite installation is required.

## Install Locally

PowerShell:

```powershell
git clone git@github.com:pavelber/livejournal-mcp.git
Set-Location "livejournal-mcp"
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e .
```

macOS/Linux:

```bash
git clone git@github.com:pavelber/livejournal-mcp.git
cd livejournal-mcp
python3 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install -e .
```

## Environment Variables

Required:

- `LJ_USERNAME`: LiveJournal username.
- `LJ_PASSWORD`: LiveJournal password.

Optional:

- `LJ_JOURNAL`: target journal. Defaults to `LJ_USERNAME`.
- `LJ_BASE_URL`: defaults to `https://www.livejournal.com`.
- `LJ_CLIENT_VERSION`: defaults to `Cursor-MCP/0.1.0`.
- `LJ_CACHE_PATH`: SQLite cache path. On Windows, a good explicit path is `C:\Users\you\AppData\Local\livejournal-mcp\livejournal.sqlite3`.

Do not commit credentials. Put them in your MCP client config or environment.

## Cursor

Add this to your Cursor MCP config, replacing paths and credentials.

Windows:

```json
{
  "mcpServers": {
    "livejournal": {
      "command": "C:\\path\\to\\livejournal-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "livejournal_mcp.server"],
      "env": {
        "LJ_USERNAME": "your_livejournal_username",
        "LJ_PASSWORD": "your_livejournal_password",
        "LJ_JOURNAL": "your_livejournal_username",
        "LJ_CACHE_PATH": "C:\\Users\\you\\AppData\\Local\\livejournal-mcp\\livejournal.sqlite3"
      }
    }
  }
}
```

macOS/Linux:

```json
{
  "mcpServers": {
    "livejournal": {
      "command": "/path/to/livejournal-mcp/.venv/bin/python",
      "args": ["-m", "livejournal_mcp.server"],
      "env": {
        "LJ_USERNAME": "your_livejournal_username",
        "LJ_PASSWORD": "your_livejournal_password",
        "LJ_JOURNAL": "your_livejournal_username",
        "LJ_CACHE_PATH": "/Users/you/.local/share/livejournal-mcp/livejournal.sqlite3"
      }
    }
  }
}
```

Reload MCP servers or restart Cursor.

## Claude Desktop

Edit `claude_desktop_config.json`.

Windows:

```json
{
  "mcpServers": {
    "livejournal": {
      "command": "C:\\path\\to\\livejournal-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "livejournal_mcp.server"],
      "env": {
        "LJ_USERNAME": "your_livejournal_username",
        "LJ_PASSWORD": "your_livejournal_password",
        "LJ_JOURNAL": "your_livejournal_username",
        "LJ_CACHE_PATH": "C:\\Users\\you\\AppData\\Local\\livejournal-mcp\\livejournal.sqlite3"
      }
    }
  }
}
```

macOS/Linux:

```json
{
  "mcpServers": {
    "livejournal": {
      "command": "/path/to/livejournal-mcp/.venv/bin/python",
      "args": ["-m", "livejournal_mcp.server"],
      "env": {
        "LJ_USERNAME": "your_livejournal_username",
        "LJ_PASSWORD": "your_livejournal_password",
        "LJ_JOURNAL": "your_livejournal_username",
        "LJ_CACHE_PATH": "/Users/you/.local/share/livejournal-mcp/livejournal.sqlite3"
      }
    }
  }
}
```

Restart Claude Desktop after editing the config.

## Claude Code

From the cloned repo, register the server with an MCP config that points at the virtualenv Python. If your Claude Code installation supports project MCP config files, use the same `mcpServers` JSON shown above.

You can also run the server directly for debugging:

```powershell
.\.venv\Scripts\python.exe -m livejournal_mcp.server
```

```bash
./.venv/bin/python -m livejournal_mcp.server
```

## Windsurf, Cline, Continue, And Other MCP Clients

Use the same stdio command shape:

```json
{
  "mcpServers": {
    "livejournal": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "livejournal_mcp.server"],
      "env": {
        "LJ_USERNAME": "your_livejournal_username",
        "LJ_PASSWORD": "your_livejournal_password",
        "LJ_JOURNAL": "your_livejournal_username",
        "LJ_CACHE_PATH": "/absolute/path/to/livejournal.sqlite3"
      }
    }
  }
}
```

On Windows, use the virtualenv executable:

```text
C:\path\to\livejournal-mcp\.venv\Scripts\python.exe
```

On macOS/Linux, use:

```text
/path/to/livejournal-mcp/.venv/bin/python
```

## Common Workflows

Check credentials:

```text
Use the livejournal MCP server and run check_login.
```

Read recent entries:

```text
Use list_entries with limit 10.
```

Read entries for a date:

```text
Use get_entries_for_date with date "2026-06-09".
```

Build a searchable cache:

```text
Use cache_recent_entries with limit 50.
Then use search_cached_entries for "search words".
```

Post safely:

```text
Use create_post with dry_run true.
```

`create_post` defaults to `dry_run: true` and `security: private`. Set `dry_run: false` only when you are ready to publish.

## Notes

- LiveJournal XML-RPC sometimes returns text fields as XML-RPC binary values. This server converts them to normal strings before returning MCP responses.
- The cache stores entry text and metadata, not your password.
- For full historical sync, use LiveJournal's `syncitems` workflow gradually and cache results with `cache_synced_entries`.