Docs

MCPサーバー

monthlet 0.13.1 以降

monthlet は MCP サーバとしてふるまえます。Claude Code のようなアプリ外のエージェントが、ファイルを直接触るのではなく monthlet を通して vault のノートを読み書きできます。このページは、公開しているツールと、それぞれが何を保証するかをまとめたものです。アプリ内での操作手順はアプリのヘルプをご覧ください。

概要

有効にすると monthlet が MCP の接続を待ち受け、決まったツールを公開します。ノートの検索と一覧・ノートの Markdown での読み取り・スプレッドシートのセルとチャートの数値の読み取り、そして別途許可したときだけノートの作成と書き換え、ノートとフォルダの移動・名前の変更です。

アプリの起動が前提です。接続できるのは monthlet を起動している間だけで、公開される vault は、いま開いている 1 つです。vault を切り替えると公開対象も切り替わります。

すべての操作は monthlet を経由します。ファイルを書くのは常にアプリ自身であり、それによって変更履歴・検索インデックス・開いている編集画面が、エージェントの操作と食い違わないようにしています。

セットアップ

monthlet の設定 → コネクタ → 外部エージェントに公開を開き、公開するをオンにします。
セットアップのコマンドをコピーを押し、コピーした内容をターミナルで実行します。Claude Code に登録されます。
書き込みも許可する場合は、同じ画面の書き込みを許可をオンにします。既定はオフです。
ノートやフォルダの移動・名前の変更も許可する場合は、その下の移動・名前の変更を許可をオンにします。既定はオフで、書き込みの許可も必要です。

コマンドは次の形です。実際のものは設定画面からコピーしてください（アプリの置き場所によってパスが変わります）。

claude mcp add --scope user monthlet -- \
  /Applications/monthlet.app/Contents/Resources/bin/monthlet-mcp

これは 2 つある接続方法のうち新しいほうで、monthlet 0.13.3 以降が必要です（このコマンドを同梱したのが 0.13.3 からです）。設定画面でも見分けられます。セットアップにコマンドをコピーと HTTP で直接（トークン込み）の 2 つが並んでいれば使えます。ボタンが 1 つだけの場合は、下の HTTP でつなぐ方法をお使いください。

このコマンドの実行には、お使いの環境の Node.js が必要です。monthlet が同梱しているのはスクリプトであり、それを動かす実行環境ではありません。
エージェント側に登録されるのは、このコマンドのパスだけです。トークンは設定ファイルに書き込まれません。実行のたびに、コマンドがトークンとポートを monthlet から読み取ります。
そのため、トークンを作り直しても登録し直す必要はありません。既定のポートが使用中で別のポートに変わった場合も同様です。
--scope user は、プロジェクトごとの設定ファイルではなく、ユーザー単位で一度だけ登録するためのものです。

HTTP で直接つなぐ

コマンドを起動できないクライアントや、streamable HTTP しか話さないクライアントは、接続先へ直接つなげます。こちらは同じ画面の HTTP で直接（トークン込み）からコピーしてください（トークンを含み、既定のポートが使用中のときはポート番号も変わります）。

claude mcp add --scope user --transport http monthlet \
  http://127.0.0.1:27180/mcp --header "Authorization: Bearer <token>"

こちらでは --scope user にもう 1 つの意味があります。トークンがユーザー設定に保存され、コミットされうるプロジェクト内のファイルには書かれません。
トークンはクライアントの設定ファイルに書き込まれます。そのため、設定画面でトークンを作り直したときは登録し直しが必要です。それまでのトークンはその場で使えなくなります。
streamable HTTP に対応した MCP クライアントであれば、同じ接続先とヘッダーで接続できます。

ツール

読み取り

ツール	用途	主な引数	返すもの
`search_notes`	ノートとスプレッドシートの全文検索。タイトル・本文・タグが対象。	`query`（必須）・`tags`・`includeArchived`・`limit`（既定20・monthlet 1.1.0以降は上限199）	関連度順の該当件を`results`で返す。各件にパス・タイトル・種別・更新日・タグ・前後のスニペット。monthlet 1.1.0以降は、`limit`で切ったかどうかの`truncated`と、使った`limit`も返す。`truncated`がtrueなら当たりはまだあるので、`limit`を上げるか語を絞る。
`grep_notes`	ノートの本文を、完全一致か正規表現で検索する（grepと同じ使い方）。対象はread_noteが返すのと同じMarkdown。スプレッドシートは対象外。monthlet 1.1.0以降。	`pattern`（必須）・`regex`・`ignoreCase`・`path`（フォルダ、または`dev/*/.html`のようなグロブ）・`outputMode`（`lines` / `files`）・`context`（0〜5）・`includeArchived`・`limit`（既定100・上限500）	当たった行（パス・行番号・行の中身）。`files`ならノートごとの件数。ほかに、limitに関係なく数えた`totalMatches`・`totalFiles`、`truncated`、読めずに飛ばしたノートの数`skipped`。0件のときは`skipped`が0であることを見てから「無い」と判断する。
`list_notes`	ノートとスプレッドシートの一覧。更新の新しい順。	`folder`・`includeExcerpt`・`includeArchived`・`limit`（既定 200）	パス・フォルダ・タイトル・種別（ノート / シート）・更新日・タグ・ピン・アーカイブ。指定すると本文冒頭 160 字も。
`read_note`	ノートの本文を Markdown で読む。スプレッドシートは対象外（read_sheet_range を使う）。	`path`（必須）・`offset`（読み始める行・1始まり）・`limit`（読む行数）	パス・タイトル・タグ・更新日・本文（Markdown）・版（`version`）。monthlet 1.1.0以降は、本文の先頭に`---`で囲んだfrontmatterが付く。中身はOKF（Open Knowledge Format）の種別のキー`type`（ノートが持っていなければ`Note`）と、ノート独自のキー（title・tags・pinned・archivedとmonthletが持つ日付以外）。ほかに`startLine`・`endLine`・`totalLines`と、一部だけを返したかどうかの`partial`。一部だけを返したときは`version`が付かない。`offset`と`limit`はmonthlet 1.1.1以降。
`read_sheet_range`	vault 内のスプレッドシートのセルを読む。	`path`（この接続では必須）・`range`（A1 形式）・`sheet_id`	セルの値。range を省略すると使用範囲の概観。
`read_chart_data`	ノート内のチャートの数値を読む。	`path`（必須）・`id`	チャートごとのラベルと系列の値。シートに連動している場合は参照元のパスと範囲も。
`list_folders`	vaultのフォルダのツリーを返す（空のフォルダも含む）。ノートを作る場所や移動先を決める前に、構造を見るのに使う。monthlet 1.1.1以降。	`path`（起点のフォルダ）・`depth`（起点の直下が1）	フォルダごとのパス・名前・`documents`（直下のノートとスプレッドシートの数）・`totalDocuments`（配下すべての数）・子フォルダ。最大2,000フォルダで、`depth`か上限で切ったところには`truncated`が付く。
`list_files`	フォルダの中のファイルを、どのノートに付いているかと関係なく列挙する。既定では画像・PDF・動画・音声などの添付だけ。あるノートに付いている添付だけを引くときは`list_attachments`を使う。monthlet 1.1.1以降。	`path`・`recursive`（既定true）・`include`（`files` / `notes` / `all`）	ファイルごとのパス・種別（note / image / video / audio / other）・サイズ。
`get_backlinks`	指定したノートへリンクしているノートを一覧する。クラウドにあってまだダウンロードされていないノートは含まない。monthlet 1.1.1以降。	`path`（必須）	リンク元のノートごとのパスとタイトル。
`list_attachments`	あるノートに付いている添付を一覧する。本文から参照しているもの（`where: body`）と、添付パネルだけにあるもの（`where: panel`）の両方が出る。フォルダの中のファイルをノートと関係なく一覧するときは`list_files`を使う。monthlet 1.1.1以降。	`path`（必須）	添付ごとの`path`（`readWith`のツールにそのまま渡せる）・本文に書かれている参照・`where`・`kind`（image / pdf / text / video / audio / other）・`exists`・`size`と、中身を読むツールの`readWith`（`view_image` / `read_pdf` / `read_file`。読めないものは空）。
`view_image`	vault内の画像（PNG・JPEG・GIF・WebP）を、エージェントが見られる形で返す。monthlet 1.1.1以降。	`path`（必須。`list_attachments`の`path`をそのまま渡せる）	MCPの画像コンテンツとしての画像。
`read_pdf`	vault内のPDFから文字を取り出す。図表やレイアウトは含まず、文字の層が無いスキャンしたPDFはエラーになる。monthlet 1.1.1以降。	`path`（必須）	PDFの文字。
`read_file`	vault内のテキストのファイル（.md・.txt・.csv・.jsonなど）を読む。ノートは`read_note`、PDFは`read_pdf`で読む。monthlet 1.1.1以降。	`path`（必須）	ファイルの中身。

書き込み

これらは書き込みを許可がオンのときだけ現れます。パスは vault からの相対パスで、読み取り系のツールが返すものと同じです。

ツール	用途	主な引数	返すもの
`create_note`	Markdownからノートを作る。指定したフォルダが無ければ作られる。monthlet 1.1.0以降は、先頭のfrontmatterのtagsがノートのタグに、それ以外のキーがノートのfrontmatterになる（タイトルは引数の`title`）。monthlet 1.1.1以降は、本文の`[[ノート名]]`が内部リンクになる。	`title`（必須）・`markdown`（必須）・`folder`・`tags`（monthlet 1.1.1以降）	作成したノートのパスとタイトル。同じタイトルが既にあるときは連番が付く。monthlet 1.1.1以降はタグと、どのノートにも当たらず文字のまま残った`[[...]]`の名前（`unresolvedWikilinks`）も返す。
`update_note`	ノートの本文をMarkdownで置き換える。`read_note`が返した`version`を渡す。monthlet 1.1.0以降は、先頭のfrontmatterをノートのfrontmatterとして保存する（省くと今のまま・空の`---` `---`で消す）。monthlet 1.1.1以降は、本文の`[[ノート名]]`が内部リンクになる。	`path`（必須）・`markdown`（必須）・`version`（1.0.2から必須）	パス・タイトル・保たれたプレースホルダ・消えたプレースホルダ・書いたあとの`version`。titleやtagsのようにmonthletが管理するキーは、ここではfrontmatterで変えられない。書いたときは`ignoredFrontmatterKeys`で知らせる。monthlet 1.1.1以降は`unresolvedWikilinks`も返す。
`edit_note`	ノートの本文の一部を置き換える（monthlet 1.1.0以降）。`read_note`が返した本文の中の文字列`old_string`を`new_string`に置き換え、ほかの部分は元のまま残す。`read_note`が返した`version`を渡す。	`path`（必須）・`old_string`（必須）・`new_string`（必須・消すときは`""`）・`replace_all`・`version`（必須）	`update_note`と同じものと、置き換えた箇所の数`replacements`。monthlet 1.1.1以降は、`new_string`の`[[ノート名]]`が内部リンクになり、どのノートにも当たらなかった名前を`unresolvedWikilinks`で返す。
`create_folder`	空のフォルダを作る。途中の階層も作られる。	`path`（必須）	作成したフォルダ。
`create_sheet`	行データからスプレッドシートを作る。作成時に数式と書式は設定しない。	`title`（必須）・`rows`（必須）・`folder`	作成したスプレッドシートのパスとタイトル。
`update_tags`	ノートかスプレッドシートのタグを足す・外す。本文は変わらない。大文字小文字や全角半角の違いは同じタグとして扱い、先頭の#は付けても付けなくてもよい。monthlet 1.1.1以降。	`path`（必須）・`add`・`remove`・`version`	パスと、結果として付いているタグ。渡した`version`がまだ一致していれば、書いたあとの`version`も返るので、読み直さずに`update_note`へ渡せる。
`add_attachment`	ノートに添付を足す。中身をbase64で渡すとノートと同じフォルダに保存し（同名があれば上書きせず連番を付ける）、vault内に既にあるファイルを渡すとコピーせずに参照する。vaultの外のパスは受け付けないので、中身を渡す。保存できるのは画像・動画・音声・PDF・テキスト（txt・md・csv・tsv・json・log）だけで、上限は20MB。monthlet 1.1.1以降。	`path`（必須）・`data`と`filename`か`file`・`placement`（`body`か`panel`。既定は画像・動画・音声が本文の末尾、それ以外は添付パネル）・`version`	添付のパス・ノートに書いた参照・置いた場所・コピーしたかどうか。添付パネルに置いて、渡した`version`がまだ一致していれば、書いたあとの`version`も返る。

移動・名前の変更

これらは書き込みを許可と移動・名前の変更を許可の両方がオンのときだけ現れます（monthlet 1.1.0以降）。ほかのノートからの内部リンクは移動先に合わせて書き換わります。monthletで編集中（未保存）のノートは移動も名前の変更もせず、そのようなノートを含むフォルダも動かしません。削除は提供していません。

ツール	用途	主な引数	返すもの
`move_note`	ノートを別のフォルダへ移動する。ファイル名は変わらない。	`path`（必須）・`to_folder`（必須。vaultの最上位は`""`か`.`）	移動後のパス。移動先に同じ名前のファイルがあるときは番号が付く。
`move_folder`	フォルダを中身ごと別のフォルダの下へ移動する。自分自身やその下のフォルダへは移動できない。	`path`（必須）・`to_folder`（必須。vaultの最上位は`""`か`.`）	移動後のパス。
`rename_note`	ノートのタイトルを変える。ファイル名もタイトルに合わせて変わる。	`path`（必須）・`new_title`（必須）	新しいタイトルとパス。
`rename_folder`	フォルダの名前を、同じ場所のまま変える。中のノートのパスも変わる。別のフォルダの下へ動かすときはmove_folderを使う。	`path`（必須）・`new_name`（必須）	変更後のパス。

ツールが保証すること

やり取りする形式は Markdown です。 read_note が Markdown を返し、update_note とedit_noteがMarkdownを受け取ります。ファイル形式のそれ以外の部分については、何も保証していません。
Markdown で表せない要素はプレースホルダとして残ります。 チャート・埋め込み・計算ブロックは、id の付いた monthlet-block のコードフェンスとして本文に現れます。その行をそのまま残せば元の要素が保たれ、行を消すとその要素も消えます。消えたものは droppedBlocks として id とラベルで返るので、書き換えで何が失われたかは呼び出し側で分かります。プレースホルダではなく数値が要るときは read_chart_data を使います。
update_note は全置換です。差分ではなく本文全体を渡します。タイトルは対象外で、変わりません。
入れ子の箇条書きと番号付きリストも往復します（monthlet 1.1.1以降）。子の項目は親の下に字下げして書きます（5段まで）。それより前の版では平らになっていました。チェックリストの入れ子は、いまも平らになります。
edit_noteは当たった部分だけを変えます（monthlet 1.1.0以降）。old_stringは空白と改行も含めて本文と完全に一致させます。本文に複数あるときは、前後の文を足して1か所に絞るか、replace_allを指定します。Markdownから作り直すのは当たったブロックだけなので、ほかの部分（入れ子のリスト・生のHTML・プレースホルダ）は元のまま残ります。見つからないときと1か所に絞れないときは、何も書きません。
frontmatterも往復します（monthlet 1.1.0以降）。ノート独自のfrontmatterのキーは、read_noteで本文の先頭に付いて出てきて、update_noteで書き戻せます。titleやtagsのようにmonthletが管理するキーはupdate_noteでは変わらず、ignoredFrontmatterKeysで知らせます。typeを持たないノートにread_noteが付けるtype: Noteは、書き戻しても保存されません。
書き込みが断られる条件は3つです。そのノートがmonthletで編集中（未保存の変更がある）か、versionを渡していないか、そのversionを読んだあとにノートが変わっているか（人の編集・同期・別のエージェントの書き込み）です。後の2つは、read_noteで読み直してその内容をもとに書き換えれば通ります。update_noteとedit_noteは書いたあとのversionを返すので、自分で書いた直後に続けて書くときは読み直さなくてかまいません。
書く前にノート全体を読みます（monthlet 1.1.1以降）。offsetかlimitでread_noteが一部だけを返したときはversionが付かないので、その読み取りからはupdate_noteもedit_noteも書けません。先に全体を読みます。そうしないと、全置換のupdate_noteでは読んでいない行が消えてしまいます。
versionはmonthlet 1.0.2からです。それより前の版はversionを使わずに変更を判定していて、同じノートを読んだ別のエージェントの書き込みを見逃すことがありました。
add_attachmentで本文に添付を入れたあとは、read_noteで読み直してからupdate_noteします（monthlet 1.1.1以降）。前に読んだ本文には足した添付が無いので、そのまま書き戻すと添付が消えます。読み直すまでupdate_noteは断られます。update_tagsとadd_attachmentも、ノートがmonthletで編集中（未保存の変更がある）のときは断られます。
書き換え前の版は残ります。ノートの本文の変更はアプリの変更履歴に記録されるので、エージェントが何をしたかを人が確認し、前の版に戻せます。タグの変更と、添付パネルへのファイルの追加（monthlet 1.1.1以降）は本文を変えないので、履歴には残りません。
書き込みや移動・名前の変更の許可を切ると即座に効きます。接続済みのクライアントは再接続まで古いツール一覧を持っていることがありますが、実行は毎回いまの設定で判定されるため、許可していない操作は動きません。
パスは変わりえます。ファイル名とタイトルが食い違うノートをアプリで開くと、ファイル名がタイトルに合わせて変更されます。パスは現時点のものとして扱い、以前に覚えたパスを使い回さず、一覧や検索を取り直してください。

意図的に公開していない操作

アプリには存在しますが、この接続では提供していません。

ノートやフォルダの削除・マージアプリが実行前に確認を取る操作であり、この接続には確認を取る相手が画面にいないためです。移動・名前の変更はmonthlet 1.1.0まではここに含めていましたが、いまは専用のスイッチで許可できます（上記）。
既存のスプレッドシートのセル編集シートの編集は、開いているシートに対して画面を描いている側で適用されます。新規作成は提供していますが、既存のものを書き換えることはできません。
アプリの画面を動かす操作ノートを開く・検索パネルを出すといった操作は、ウィンドウの外で動くエージェントには適用先がありません。
URL の取得・スキルの保存・アプリ内ヘルプの参照monthlet の中のチャットのための機能で、外部のエージェントは自分のものを持っています。

セキュリティ

既定はオフです。有効にするまで何も待ち受けません。読み取り・書き込み・移動と名前の変更は別のスイッチで、有効にしただけでは書き込みはできず、書き込みを許可しただけでは移動も名前の変更もできません。
ローカルのみです。127.0.0.1 にのみバインドするため、ネットワークからは見えません。
すべてのリクエストにトークンが要ります。ローカルであっても Authorization: Bearer ヘッダーが必須で、Origin ヘッダーが付いたリクエストは一律で拒否します。これによりブラウザのページからは接続できません。
対象は 1 つの vault、アプリの起動中だけです。公開されるのはいま開いている vault で、monthlet が動いている間に限られます。
ノートの本文は、読んだエージェントにとって未検証の入力です。ノートには指示のように読めるテキストが書かれていることがあり、それに従って動けば、たまたま書かれていた内容に従うことになります。ここへの対処は接続側のエージェントの責務です。monthlet は本文をそのまま渡します。

互換の方針

ツールの名前と入出力は後方互換を守ります。フィールドが増えることはありますが、既存のものの意味は変えません。
呼び出し側が壊れる変更が必要なときは、既存のツールの意味を変えるのではなく、新しいツール名として提供します。
これまでに例外が1つあります。monthlet 1.0.2で、update_noteにversionが必須になりました。versionが無いと、同じノートを読んだ2つのエージェントが互いの変更を気づかずに上書きすることがあり、新しいツール名にすると安全でない古いツールが使えるまま残るためです。versionを渡さない呼び出しは、先に読むよう返して断り、書き込みはしません。
ノートのファイル内にある monthlet-blocks の JSON は、公開しているインターフェースではありません。アプリの変更に追随して変わるため、直接読まずにツールを経由してください。