Filamental

io.github.ScottninePublished by GitHub account Scottninev0.2.17Updated Oct 29, 2026

Search, read and build your Filamental knowledge graph. Local-first: notes stay on your computer.

VerifiedSTDIODesktop onlyFiles & StorageKnowledge & Memory

Overview

AI-generated overview

Local MCP server for Filamental that lets an assistant search, read and build the markdown knowledge graph in your project.

What you can do
  • Orient and read the graph: structure report, project info, node and connector types, single nodes, connections and subgraphs up to 3 hops
  • Search nodes by name, notes and property values, and find the shortest connector path between two nodes
  • Get one node's notes plus its neighbourhood as a single markdown document, with a dry run to size it first
  • Create, update and delete nodes and connectors, writing the markdown file and index together
  • Extract a heading's section into its own node or inline a node back into another, moving content rather than copying it
  • Read the structure-design guide and the on-disk format reference
When to use it
Useful when you keep notes or research in a Filamental project and want an assistant to explore the graph, answer questions from it, or add and reorganise nodes and connectors while the app shows the changes.
Requirements
Runs locally over stdio via npx (Node.js 22 or later). Requires the Filamental desktop app with the project opened in it at least once. By default it follows whichever project the app has open; an optional --project path pins it to one project. No API keys or environment variables are declared.
Before you install
Write tools change your project: create_node, update_node, delete_node, create_edge, delete_edge, extract_section and inline_section modify or delete markdown files and the index, and passing properties or relationships to update_node replaces the whole set. On Filamental's free plan a project is capped at 20 nodes, including ones an AI creates.

Installation

In SourceWeft

  1. Open Filamental in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

filamental-mcp

The Model Context Protocol server for Filamental. It lets Claude and other AI apps search, read and build the knowledge graph in your Filamental project: the same markdown files the app shows you, so every change appears in the app as it happens.

The server runs on your computer, works whether Filamental is open or closed, and makes no network requests of its own.

Requires the Filamental desktop app, with the project opened in it at least once, and Node.js 22 or later.

Setup

From Filamental

Open Settings › AI. Under Connect an AI app, Connect sets up Claude Desktop in one click. For any other app, Show setup beside Other AI apps gives the exact block for that app, with the paths for your computer filled in.

By hand

Add this to your AI app's MCP settings file (claude_desktop_config.json, .mcp.json for Claude Code, .cursor/mcp.json and so on):

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

No path is needed. The server works on whichever project Filamental has open, and follows you when you open another, with no restart. To pin it to one project instead, add "--project", "/absolute/path/to/your/project" to args.

Tools

Orient and read

ToolWhat it does
get_structure_reportA short orientation to the whole project: its classifications and connectors, the most connected nodes, the load-bearing ones, separate groups, and nodes that are unconnected or have no notes
get_contextOne node's notes plus its neighbourhood, inlined as one readable markdown document. dry_run sizes it first
find_pathThe shortest chain of connectors between two nodes, by name or UUID, with how each hop reads
search_nodesFull-text search across names, notes and property values, with an optional field filter that also works on its own
get_nodeOne node's full record, notes included
get_connectionsEvery connector on a node, stated from that node's point of view (see Arrow direction)
get_subgraphEvery node and connector within up to 3 hops of a node
get_project_infoNode and connector counts, and the classification and connector type names
list_node_typesThe project's classifications (entity types), with their colours and settings
list_connector_typesThe project's connector types, with their colours, directions and weights

Write

ToolWhat it does
create_nodeCreate a node: writes its markdown file and updates the index
update_nodeChange a node. Omitted fields stay as they are; a properties or relationships you pass replaces the whole set
delete_nodeDelete a node and its file
create_edgeConnect two nodes
delete_edgeRemove a connector
extract_sectionMove a heading's section out of a node into a node of its own, leaving a [[wikilink]] and a connector behind. dry_run previews it
inline_sectionFold a node's content back into another: the inverse of extract_section. dry_run previews it

The content is moved, never copied, so exactly one copy of any text survives.

Guides

ToolWhat it does
read_skill_guideThe full guide to designing a Filamental structure. The server sends the essentials when it connects, so this is for depth
read_format_referenceThe exact on-disk format of node files and the .filamental/ folder

Every tool carries MCP annotations (readOnlyHint, destructiveHint), so your AI app can tell the read-only tools from the ones that change or delete content.

On Filamental's free plan a project holds 20 nodes, not counting bridges, and that includes nodes an AI creates: create_node says so when a project is full. Pro has no limit.

Arrow direction

A connector's direction is one of none, outgoing, incoming or bidirectional. Nothing else is accepted, and an unrecognised value is rejected rather than stored.

On writes (create_edge, create_node, update_node) direction is stated relative to source → target: outgoing draws the arrowhead at the target, incoming draws it back at the source, bidirectional draws both, none is a plain line.

On reads (get_connections) direction is instead stated relative to the node you asked about, because that is what the user sees on screen:

FieldMeaning
nodeThe node you asked about
otherThe node at the far end
directionWhere the arrowhead is drawn, as seen from node
stored_onWhich node's file holds the relationship

This matters because which end of a connector is stored as source is simply whichever end the user happened to drag from, and it's invisible on the graph: an undirected connector looks the same either way round. So the same arrow reads as outgoing from one end and incoming from the other, and get_connections flips it for you. Filtering with direction: "outgoing" gives the edges whose arrow points away from the node you asked about. A bidirectional edge matches both outgoing and incoming, since it genuinely points both ways; undirected matches only edges with no arrow.

Use stored_on only if you're editing the underlying markdown file directly. It says nothing about what the arrow does.

CLI options

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

How it works

Every node in a Filamental project is a markdown file with YAML front matter, inside the project folder. The app also keeps a SQLite index of each project for fast search and traversal, stored in the app's own settings folder rather than in the project.

The server opens that index. Read tools query it; write tools update the markdown file and the index together, and keep any front-matter fields they don't own (Obsidian's tags and aliases, say) exactly where they were.

Compatibility

filamental-mcpFilamental appIndex schema
0.2.6 and later0.3.0 and laterv6
0.2.0 – 0.2.50.2.xv5

On a schema mismatch the server keeps working where it can, since the index is disposable, and annotates any failing call with which side to update.

Licence

MIT. The Filamental desktop app itself is proprietary; its terms are at filamental.space/terms.

Source: mcp/README.md at commit 494c612

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

3
  1. v0.2.17LatestOct 29, 2026
  2. v0.2.16Oct 26, 2026
  3. v0.2.10Sep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.