freshjots-mcp

A Model Context Protocol (MCP) server for Fresh Jots. It exposes your Fresh Jots notes as MCP tools, so any MCP client — Claude Desktop, Claude Code, Cursor, and others — can read and write them directly. Point your AI agent's output at a Fresh Jots note, log your coding sessions, or let an assistant search and update your notebook, all through the API.

MCP is an open standard for connecting AI assistants to external tools and data — think of it as a universal adapter, so one integration works across every compatible client.

What you can do

The server talks to the Fresh Jots REST API over a bearer token and exposes these tools:

Notes — list_notes, read_note, create_note, append_to_note, update_note, delete_note, move_note

Folders — list_folders, create_folder, rename_folder, delete_folder

The standout is append_to_note: it appends to a note addressed by an exact filename (e.g. ai-sessions.txt) and creates the note on first write. Call it repeatedly to accumulate a log — AI session transcripts, cron output, a running journal — in one place.

Notes are plain text through the API: rich (Trix) notes can be listed and read, but only plain notes can be created or edited here.

Requirements

Node.js 18 or newer
A Fresh Jots API token (Dev or Team plan). Create one at https://freshjots.com/settings/api_tokens. Tokens look like mn_….

Install

Until this is published to npm, build it from source:

git clone https://github.com/Goran-Arsov/freshjots-mcp.git
cd freshjots-mcp
npm install        # also builds via the prepare script
npm run build      # or build explicitly

The runnable server is then dist/index.js.

Configuration

The server reads its token from the environment:

FRESHJOTS_TOKEN (required) — your mn_… API token. FRESHJOTS_API_TOKEN is also accepted.
FRESHJOTS_BASE_URL (optional) — defaults to https://freshjots.com/api/v1. Override for a self-hosted or staging instance.
FRESHJOTS_PASSPHRASE (optional) — enables transparent client-side encryption (see below).

Encryption

Set FRESHJOTS_PASSPHRASE and the server can keep notes Fresh Jots cannot read. create_note and append_to_note take an encrypt: true argument that encrypts the body locally before it ever leaves your machine, and marks the note client-encrypted; read_note takes decrypt: true to decrypt it back. The model works in plaintext while Fresh Jots stores only ciphertext — you hold the only key, so lose the passphrase and the note is unrecoverable. Encryption is per-note and personal-only (not team notes); a note's title and metadata stay in the clear. The format (fj1: AES-256-CBC + HMAC-SHA256, PBKDF2) is interoperable with the JS, Python, Ruby, and shell clients. See https://freshjots.com/encrypted-notes.

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "freshjots": {
      "command": "node",
      "args": ["/absolute/path/to/freshjots-mcp/dist/index.js"],
      "env": { "FRESHJOTS_TOKEN": "mn_your_token_here" }
    }
  }
}

Claude Code

claude mcp add freshjots --scope user \
  -e FRESHJOTS_TOKEN='${FRESHJOTS_TOKEN}' \
  -- node /absolute/path/to/freshjots-mcp/dist/index.js

Using '${FRESHJOTS_TOKEN}' (single-quoted) stores the reference, not the secret — Claude Code expands it from your shell environment at launch, so keep export FRESHJOTS_TOKEN=mn_… in your shell profile. Or pass the literal token with -e FRESHJOTS_TOKEN=mn_… if you prefer it in the config.

Cursor

Add to ~/.cursor/mcp.json (or a project .cursor/mcp.json):

{
  "mcpServers": {
    "freshjots": {
      "command": "node",
      "args": ["/absolute/path/to/freshjots-mcp/dist/index.js"],
      "env": { "FRESHJOTS_TOKEN": "mn_your_token_here" }
    }
  }
}

Once published to npm, command: "npx", args: ["-y", "freshjots-mcp"] will replace the local path in any of the above.

Development

npm run build   # compile TypeScript to dist/
npm test        # unit tests (fetch stubbed; no network)
node smoke.mjs  # live end-to-end test against the real API — needs FRESHJOTS_TOKEN;
                # creates only clearly-marked [mcp-test] notes/folders and deletes them