Goran-Arsov/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 — listnotes, readnote, createnote, appendtonote, updatenote, deletenote, movenote
Folders — listfolders, createfolder, renamefolder, deletefolder
The standout is appendtonote: 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 . Tokens look like mn….
## Install
Until this is published to npm, build it from source:
bash
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:
FRESHJOTSTOKEN (required) — your mn… API token. FRESHJOTSAPITOKEN is also accepted.
FRESHJOTSBASEURL (optional) — defaults to https://freshjots.com/api/v1. Override for a self-hosted or staging instance.
FRESHJOTSPASSPHRASE (optional) — enables transparent client-side encryption (see below).
## Encryption
Set FRESHJOTSPASSPHRASE and the server can keep notes Fresh Jots cannot read. createnote and appendtonote take an encrypt: true argument that encrypts the body locally before it ever leaves your machine, and marks the note client-encrypted; readnote 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 .
### Claude Desktop
Add to claudedesktopconfig.json (Settings → Developer → Edit Config):
json
"mcpServers": {
"freshjots": {
"command": "node",
"args": ["/absolute/path/to/freshjots-mcp/dist/index.js"],
"env": { "FRESHJOTSTOKEN": "mnyourtokenhere" }