Fresh Jots Mcp Server

freshjots-mcp

一个用于 Fresh Jots 的 Model Context Protocol（MCP）服务。它将你的 Fresh Jots 笔记作为 MCP 工具公开，因此任何 MCP 客户端——Claude Desktop、Claude Code、Cursor 等——都可以直接读取和写入笔记。将 AI Agent 的输出指向 Fresh Jots 笔记、记录编码会话，或让助手搜索和更新笔记本，所有操作都通过 API 完成。

MCP 是一项开放标准，用于将 AI 助手连接到外部工具和数据——可以把它看作通用适配器，让同一项集成适用于所有兼容客户端。

你可以做什么

该服务通过 bearer token 与 Fresh Jots REST API 通信，并提供以下工具：

笔记 — list_notes、read_note、create_note、append_to_note、update_note、delete_note、move_note

文件夹 — list_folders、create_folder、rename_folder、delete_folder

其中最突出的是 append_to_note：它通过精确的文件名（例如 ai-sessions.txt）指定笔记并追加内容，首次写入时会创建笔记。可以重复调用它，在同一处累积日志——AI 会话记录、cron 输出、持续更新的日志等。

通过 API 处理的笔记都是纯文本：可以列出和读取富文本（Trix）笔记，但这里只能创建或编辑纯文本笔记。

要求

• Node.js 18 或更高版本
• Fresh Jots API token（Dev 或 Team 方案）。请前往 https://freshjots.com/settings/api_tokens 创建。Token 格式如 mn_…。

安装

在发布到 npm 之前，请从源代码构建：

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

之后，可运行的服务入口为 dist/index.js。

配置

服务从环境中读取 token：

• FRESHJOTS_TOKEN（必需）——你的 mn_… API token。也接受 FRESHJOTS_API_TOKEN。
• FRESHJOTS_BASE_URL（可选）——默认为 https://freshjots.com/api/v1。可覆盖此值以用于可自托管或预发布实例。
• FRESHJOTS_PASSPHRASE（可选）——启用透明的客户端加密（见下文）。

加密

设置 FRESHJOTS_PASSPHRASE 后，服务可以保存 Fresh Jots 无法读取的笔记。create_note 和 append_to_note 接受 encrypt: true 参数，会在内容离开你的设备之前在本地加密，并将笔记标记为客户端加密；read_note 接受 decrypt: true 参数，可将内容解密还原。模型处理的是明文，而 Fresh Jots 只存储密文——唯一的密钥由你持有，因此一旦丢失密码短语，笔记将无法恢复。加密按笔记进行，且仅限个人笔记（不适用于团队笔记）；笔记标题和元数据仍为明文。该格式（fj1：AES-256-CBC + HMAC-SHA256、PBKDF2）与 JS、Python、Ruby 和 shell 客户端兼容。请参阅 https://freshjots.com/encrypted-notes。

Claude Desktop

将以下内容添加到 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

使用 '${FRESHJOTS_TOKEN}'（单引号括起来）存储的是引用，而非密钥——Claude Code 会在启动时从你的 shell 环境中展开它，因此请在 shell 配置文件中保留 export FRESHJOTS_TOKEN=mn_…。如果你希望将 token 直接写入配置，也可以通过 -e FRESHJOTS_TOKEN=mn_… 传入字面值。

Cursor

将以下内容添加到 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

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

发布到 npm 后，上述配置中的本地路径都可以替换为 command: "npx"、args: ["-y", "freshjots-mcp"]。

开发

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

许可证

MIT © Goran Arsov