filamental-mcp

filamental-mcp

Filamental 向けの Model Context Protocol サーバーです。Claude などの AI アプリから、Filamental プロジェクトのナレッジグラフを検索、読み取り、構築できます。アプリに表示されるものと同じ Markdown ファイルを使うため、変更はその都度アプリに反映されます。

このサーバーはお使いのコンピューター上で動作し、Filamental が開いているかどうかにかかわらず機能します。また、サーバー自身がネットワークリクエストを送信することはありません。

必要条件：Filamental デスクトップアプリがインストールされ、プロジェクトがそのアプリで少なくとも一度開かれていること、Node.js 22 以降。

---

セットアップ

Filamental から

Settings › AI を開きます。Connect an AI app の下にある Connect をクリックすると、Claude Desktop をワンクリックでセットアップできます。それ以外のアプリの場合は、Other AI apps の横にある Show setup をクリックすると、お使いのコンピューターのパスが入力された、そのアプリ用の設定ブロックが表示されます。

手動で設定

AI アプリの MCP 設定ファイル（claude_desktop_config.json、Claude Code の場合は .mcp.json、.cursor/mcp.json など）に、次の内容を追加します。

{
  "mcpServers": {
    "filamental": {
      "command": "npx",
      "args": ["-y", "filamental-mcp"]
    }
  }
}

パスは不要です。サーバーは Filamental で開いているプロジェクトで動作し、再起動せずに、別のプロジェクトを開いたときもそれに追従します。代わりに特定のプロジェクトに固定するには、"--project", "/absolute/path/to/your/project" を args に追加します。

---

ツール

概要の把握と読み取り

ツール	内容
get_structure_report	プロジェクト全体の概要です。分類とコネクター、最も多く接続されたノード、重要なノード、独立したグループ、接続されていないノードやメモのないノードを確認できます
get_context	1 つのノードのメモと近傍を、読みやすい 1 つの Markdown ドキュメントにまとめて表示します。dry_run で事前にサイズを確認できます
find_path	名前または UUID で指定した 2 つのノード間をつなぐ最短のコネクター列と、各経路がどのように読み取れるかを表示します
search_nodes	名前、メモ、プロパティ値を全文検索します。オプションのフィールド filter は単独でも使用できます
get_node	メモを含む、1 つのノードの完全なレコードを表示します
get_connections	ノードのすべてのコネクターを、そのノードの視点から表示します（矢印の向きを参照）
get_subgraph	ノードから最大 3 ホップ以内にあるすべてのノードとコネクターを表示します
get_project_info	ノードとコネクターの数、および分類名とコネクタータイプ名を表示します
list_node_types	プロジェクトの分類（エンティティタイプ）を色と設定とともに表示します
list_connector_types	プロジェクトのコネクタータイプを色、方向、重みとともに表示します

書き込み

ツール	内容
create_node	ノードを作成します。Markdown ファイルを書き込み、インデックスを更新します
update_node	ノードを変更します。省略したフィールドはそのまま残ります。渡した properties または relationships は、全体を置き換えます
delete_node	ノードとそのファイルを削除します
create_edge	2 つのノードを接続します
delete_edge	コネクターを削除します
extract_section	見出しのセクションをノードから切り出し、独立したノードに移します。元の場所には [[wikilink]] とコネクターを残します。dry_run でプレビューできます
inline_section	ノードの内容を別のノードに戻します。extract_section の逆の操作です。dry_run でプレビューできます

内容はコピーされず、移動されるため、どのテキストも必ず 1 つだけ残ります。

ガイド

ツール	内容
read_skill_guide	Filamental の構造を設計するための完全なガイドです。サーバーは接続時に要点を送信するため、このツールでは詳しい内容を確認できます
read_format_reference	ノードファイルと .filamental/ フォルダーの正確なディスク上の形式です

各ツールには MCP アノテーション（readOnlyHint、destructiveHint）が付与されているため、AI アプリは読み取り専用のツールと、内容を変更または削除するツールを区別できます。

Filamental の無料プランでは、プロジェクトに保存できるノードはブリッジを除いて 20 個までです。AI が作成するノードもこの数に含まれます。プロジェクトが上限に達すると、create_node がそのことを知らせます。Pro には上限がありません。

矢印の向き

コネクターの direction は none、outgoing、incoming、bidirectional のいずれかです。それ以外は 受け付けられず、認識されない値は保存されずに拒否されます。

書き込み（create_edge、create_node、update_node）では、向きは source → target を基準に指定します。outgoing はターゲット側に矢印の先端を描画し、incoming は ソース側に矢印の先端を描画し、bidirectional は両側に描画し、none は単なる線を描画します。

読み取り（get_connections）では、向きは問い合わせたノードを基準に指定されます。これはユーザーが画面上で見る向きです。

フィールド	意味
node	問い合わせたノード
other	反対側の端にあるノード
direction	node から見て、矢印の先端が描画される位置
stored_on	関係がどちらのノードのファイルに保存されているか

これは、コネクターのどちら側が source として保存されるかが、ユーザーがどちら側からドラッグしたかだけで決まり、グラフ上では見えないためです。無向コネクターはどちら向きでも同じに見えます。そのため、同じ矢印でも片方の端からは outgoing、もう片方の端からは incoming として読み取られ、get_connections はその向きを反転します。direction: "outgoing" でフィルタリングすると、問い合わせたノードから離れる方向を向いた矢印を持つエッジが返されます。bidirectional エッジは実際に両方向を向いているため、outgoing と incoming の両方に一致します。undirected は矢印のないエッジにのみ一致します。

stored_on は、基となる Markdown ファイルを直接編集する場合にのみ使用してください。矢印の向きには関係ありません。

---

CLI オプション

filamental-mcp                              Follow the project Filamental has open
filamental-mcp --project <path>             Pin to the project at <path>
filamental-mcp --project <path> --db <path> Also override the SQLite index path (for testing)

---

仕組み

Filamental プロジェクト内の各ノードは、プロジェクトフォルダーにある YAML フロントマター付きの Markdown ファイルです。アプリは各プロジェクトの SQLite インデックスも保持しており、高速な検索とトラバーサルに使用します。このインデックスはプロジェクト内ではなく、アプリ独自の設定フォルダーに保存されます。

サーバーはこのインデックスを開きます。読み取りツールはインデックスを検索し、書き込みツールは Markdown ファイルとインデックスを同時に更新します。また、所有していないフロントマターのフィールド（Obsidian の tags や aliases など）は、元の位置のまま保持します。

---

互換性

filamental-mcp	Filamental アプリ	インデックススキーマ
0.2.6 以降	0.3.0 以降	v6
0.2.0 – 0.2.5	0.2.x	v5

スキーマが一致しない場合でも、インデックスは再生成できるため、サーバーは可能な範囲で動作を続けます。また、失敗した呼び出しには、どちらを更新すべきかを注記します。

---

ライセンス

MIT。Filamental デスクトップアプリ自体はプロプライエタリです。利用規約はfilamental.space/termsをご覧ください。