filamental-mcp

filamental-mcp

Filamental 的模型上下文协议服务。它让 Claude 和其他 AI 应用能够搜索、阅读并构建 Filamental 项目中的知识图谱：也就是应用中显示的那些 Markdown 文件，因此每次更改都会即时显示在应用中。

服务在你的电脑上运行，无论 Filamental 是否打开都能正常工作，并且不会自行发起网络请求。

需要 Filamental 桌面应用，且至少在其中打开过一次项目；还需要 Node.js 22 或更高版本。

---

设置

在 Filamental 中设置

打开 设置 › AI。在 连接 AI 应用下，点击 连接即可一键设置 Claude Desktop。 对于其他应用，点击 其他 AI 应用旁的 显示设置，即可获取该应用所需的准确配置块，其中已填入你电脑上的路径。

手动设置

将以下内容添加到 AI 应用的 MCP 设置文件中（claude_desktop_config.json、Claude Code 的 .mcp.json、.cursor/mcp.json 等）：

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

无需指定路径。服务会使用 Filamental 当前打开的项目；当你打开其他项目时，它也会随之切换，无需重启。若要固定使用某个项目，则在 args 中添加 "--project", "/absolute/path/to/your/project"。

---

工具

定位与阅读

工具	功能
get_structure_report	快速了解整个项目：包括分类和连接类型、连接最多的节点、承载关键关系的节点、独立分组，以及没有连接或没有备注的节点
get_context	将单个节点的备注及其邻域内联为一份易读的 Markdown 文档。dry_run 会先计算大小
find_path	查找两个节点之间最短的连接链，可按名称或 UUID 查找，并说明每一段连接的含义
search_nodes	对名称、备注和属性值进行全文搜索；可选的字段 filter 也可单独使用
get_node	获取单个节点的完整记录，包括备注
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	连接两个节点
delete_edge	移除一条连接
extract_section	将节点中某个标题下的章节移出，创建为独立节点，并留下 [[wikilink]] 和一条连接。dry_run 可预览操作
inline_section	将节点内容折叠回另一个节点；这是 extract_section 的逆操作。dry_run 可预览操作

内容会被移动，而非复制，因此任何文本都只会保留一份。

指南

工具	功能
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 只匹配没有箭头的边。

只有在直接编辑底层 Markdown 文件时才使用 stored_on。它并不表示箭头的方向。

---

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 front matter 的 Markdown 文件。应用还会为每个项目维护一个 SQLite 索引，以便快速搜索和遍历；该索引存储在应用自己的设置文件夹中，而不是项目内。

服务会打开该索引。读取工具会查询索引；写入工具会同时更新 Markdown 文件和索引，并原样保留它们不管理的任何 front matter 字段（例如 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。