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）	関連度順の該当件。各件にパス・タイトル・種別・更新日・タグ・前後のスニペット。
`list_notes`	ノートとスプレッドシートの一覧。更新の新しい順。	`folder`・`includeExcerpt`・`includeArchived`・`limit`（既定 200）	パス・フォルダ・タイトル・種別（ノート / シート）・更新日・タグ・ピン・アーカイブ。指定すると本文冒頭 160 字も。
`read_note`	ノートの本文を Markdown で読む。スプレッドシートは対象外（read_sheet_range を使う）。	`path`（必須）	パス・タイトル・タグ・更新日・本文（Markdown）。
`read_sheet_range`	vault 内のスプレッドシートのセルを読む。	`path`（この接続では必須）・`range`（A1 形式）・`sheet_id`	セルの値。range を省略すると使用範囲の概観。
`read_chart_data`	ノート内のチャートの数値を読む。	`path`（必須）・`id`	チャートごとのラベルと系列の値。シートに連動している場合は参照元のパスと範囲も。

書き込み

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

ツール	用途	主な引数	返すもの
`create_note`	Markdown からノートを作る。指定したフォルダが無ければ作られる。	`title`（必須）・`markdown`（必須）・`folder`	作成したノートのパスとタイトル。同じタイトルが既にあるときは連番が付く。
`update_note`	ノートの本文を Markdown で置き換える。	`path`（必須）・`markdown`（必須）	パス・タイトル・保たれたプレースホルダ・消えたプレースホルダ。
`create_folder`	空のフォルダを作る。途中の階層も作られる。	`path`（必須）	作成したフォルダ。
`create_sheet`	行データからスプレッドシートを作る。作成時に数式と書式は設定しない。	`title`（必須）・`rows`（必須）・`folder`	作成したスプレッドシートのパスとタイトル。

ツールが保証すること

やり取りする形式は Markdown です。 read_note が Markdown を返し、update_note が Markdown を受け取ります。ファイル形式のそれ以外の部分については、何も保証していません。
Markdown で表せない要素はプレースホルダとして残ります。 チャート・埋め込み・計算ブロックは、id の付いた monthlet-block のコードフェンスとして本文に現れます。その行をそのまま残せば元の要素が保たれ、行を消すとその要素も消えます。消えたものは droppedBlocks として id とラベルで返るので、書き換えで何が失われたかは呼び出し側で分かります。プレースホルダではなく数値が要るときは read_chart_data を使います。
update_note は全置換です。差分ではなく本文全体を渡します。タイトルは対象外で、変わりません。
書き込みが断られる条件は 2 つです。そのノートが monthlet で編集中（未保存の変更がある）か、read_note で読んだあとにノートが変わっているかです。後者は、read_note で読み直してその内容をもとに書き換えれば通ります。
書き換え前の版は残ります。書き込みはアプリの変更履歴に記録されるので、エージェントが何をしたかを人が確認し、前の版に戻せます。
書き込みの許可を切ると即座に効きます。接続済みのクライアントは再接続まで古いツール一覧を持っていることがありますが、実行は毎回いまの設定で判定されるため、許可していない操作は動きません。
パスは変わりえます。ファイル名とタイトルが食い違うノートをアプリで開くと、ファイル名がタイトルに合わせて変更されます。パスは現時点のものとして扱い、以前に覚えたパスを使い回さず、一覧や検索を取り直してください。

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

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

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

セキュリティ

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

互換の方針

ツールの名前と入出力は後方互換を守ります。フィールドが増えることはありますが、既存のものの意味は変えません。
呼び出し側が壊れる変更が必要なときは、既存のツールの意味を変えるのではなく、新しいツール名として提供します。
ノートのファイル内にある monthlet-blocks の JSON は、公開しているインターフェースではありません。アプリの変更に追随して変わるため、直接読まずにツールを経由してください。