Fresh Jots Mcp Server

freshjots-mcp

Fresh Jots 用の Model Context Protocol（MCP）サーバーです。Fresh Jots のノートを MCP ツールとして公開するため、Claude Desktop、Claude Code、Cursor など、あらゆる MCP クライアントからノートを直接読み書きできます。AI エージェントの出力先を Fresh Jots のノートにしたり、コーディングセッションを記録したり、アシスタントにノートブックの検索や更新を任せたりできます。すべて API 経由で行えます。

MCP は、AI アシスタントを外部のツールやデータに接続するためのオープンな標準です。いわば共通アダプターのようなもので、1 つの統合で、互換性のあるすべてのクライアントで利用できます。

できること

このサーバーはベアラートークンを使って 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 の出力、日々の記録などを 1 か所に蓄積できます。

API 経由で扱うノートはプレーンテキストです。リッチ（Trix）ノートの一覧表示と読み取りはできますが、ここで作成または編集できるのはプレーンノートのみです。

要件

• Node.js 18 以降
• Fresh Jots API トークン（Dev または Team プラン）。https://freshjots.com/settings/api_tokens で作成できます。トークンの形式は 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 にあります。

設定

サーバーは環境変数からトークンを読み込みます。

• FRESHJOTS_TOKEN（必須）— mn_… 形式の API トークンです。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、シェルの各クライアントと相互運用できます。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 は起動時にシェル環境から展開するため、シェルのプロファイルに export FRESHJOTS_TOKEN=mn_… を設定しておいてください。または、設定ファイルにトークンを直接記述してもよい場合は、-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