@workjournal/mcp-server

MCP server for Workjournal — provides tools for creating, searching, and listing journal entries from any MCP-compatible AI agent.

Breaking changes in 0.5.0

• Removed create_workspace. Workspace creation is API-only until a paid-tier signup flow ships; agents should not invent workspaces on the user's behalf.
• Added rename_journal(workspace_slug, journal_slug, new_name) — change a journal's display name. The slug stays the same, so existing links keep working.
• Added set_journal_slug(workspace_slug, journal_slug, new_slug) — change a journal's URL slug. Tool description warns the LLM that this breaks existing <workspace>/<journal> links (they will return 404).

Migration: nothing for read tools. If you scripted create_workspace, switch to creating workspaces via the API or the web UI.

Breaking changes in 0.4.0

Every journal/entry tool now takes slugs instead of UUIDs. The mental model:

• A workspace is your top-level container, identified by workspace_slug (e.g. acme, juliusz-personal).
• A journal lives inside a workspace, identified by journal_slug (e.g. engineering-notes, daily).
• Entries inside a journal are identified by their per-journal integer index (#1, #2, …) — unchanged.

Before (0.3.x):

get_entry({ journal_id: "8a4f…uuid…", index: 7 })

After (0.4.0):

get_entry({ workspace_slug: "acme", journal_slug: "engineering-notes", index: 7 })

New tools: list_workspaces, get_workspace. Auth tools (auth_login, auth_complete, auth_status) are unchanged.

Discovery flow for an agent that doesn't know any slugs yet:

1. Call list_workspaces → pick a workspace_slug.
2. Call list_journals(workspace_slug) → pick a journal_slug.
3. Call list_entries, last_entries, get_entry, create_entry, etc. with both slugs.

Internal handles that are not user-visible stay UUIDs: invitation_id (for delete_invitation) and user_id (for delete_member, since user IDs come from Supabase auth).

Usage

Run via npx (no install needed):

npx @workjournal/mcp-server

Authentication

The server reads credentials from ~/.workjournal/credentials.json. Create them once by signing in — either with npx @workjournal/cli auth login, or by asking your agent to run the server's built-in auth_login tool, which prints an authorize URL and accepts the 8-character code your browser displays after approval.

MCP client configuration

Claude Desktop / Cowork

Add to your MCP settings:

{
  "mcpServers": {
    "workjournal": {
      "command": "npx",
      "args": ["-y", "@workjournal/mcp-server"]
    }
  }
}

Claude Code

Same config in .claude/settings.json. After /mcp reconnect, the sign-in URL appears on stderr — open it, approve, paste the 8-character code back to your agent, and it'll call auth_complete for you.

Perplexity (Mac, local mode)

Add via Settings → Connectors → Simple tab. Command: npx @workjournal/mcp-server.

Available tools

Naming convention: <operation>_<resource>. Plural resource for collection results, singular for single-item operations. Most non-auth tools take workspace_slug (and, where relevant, journal_slug) as their leading arguments — list_workspaces is the only exception, since it operates above the workspace boundary.

| Tool | Arguments | Description | |------|-----------|-------------| | list_workspaces | — | List workspaces you own or belong to | | get_workspace | workspace_slug | Get a workspace by slug | | list_journals | workspace_slug | List journals in a workspace | | get_journal | workspace_slug, journal_slug | Get a journal by slug | | create_journal | workspace_slug, name, description? | Create a journal — returns the new journal_slug | | rename_journal | workspace_slug, journal_slug, new_name | Rename a journal (display name only — slug unchanged) | | set_journal_slug | workspace_slug, journal_slug, new_slug | Change a journal's URL slug (breaks existing links) | | delete_journal | workspace_slug, journal_slug | Delete a journal and all entries (irreversible) | | list_entries | workspace_slug, journal_slug, limit? | List recent entries (slim — no body) | | last_entries | workspace_slug, journal_slug, limit? | Return the N most recent entries with full body | | get_entry | workspace_slug, journal_slug, index | Get one entry by per-journal index | | create_entry | workspace_slug, journal_slug, summary, what_changed | Create an entry | | delete_entry | workspace_slug, journal_slug, index | Delete an entry by index | | search_entries | workspace_slug, journal_slug, query | Search entries by keyword | | list_members | workspace_slug, journal_slug | List members of a journal | | delete_member | workspace_slug, journal_slug, user_id | Remove a member (UUID) | | list_invitations | workspace_slug, journal_slug | List invitations for a journal | | create_invitation | workspace_slug, journal_slug, email | Invite a collaborator by email | | delete_invitation | workspace_slug, journal_slug, invitation_id | Revoke an invitation (UUID) | | export_journal | workspace_slug, journal_slug, format? | Export as json, md, or csv | | auth_login | — | Start the sign-in flow — prints an authorize URL | | auth_complete | code | Finish sign-in with the 8-character code | | auth_status | — | Report whether stored credentials are valid |

Links

• Workjournal
• Get Started