filamental-mcp

filamental-mcp

Un servidor local de Model Context Protocol que conecta asistentes de IA (Claude Desktop, Claude Code, etc.) directamente a tu grafo de conocimiento de Filamental.

El servidor lee y escribe en tu bóveda -- buscando nodos, siguiendo conexiones, creando y actualizando contenido -- mientras Filamental está en ejecución o cerrado. Se comunica con el mismo índice SQLite que usa la aplicación, por lo que los cambios son visibles de inmediato cuando abres Filamental.

Requiere Node.js 22+ y la aplicación de escritorio Filamental.

---

Requisitos previos

• Filamental instalado y al menos una bóveda abierta (esto inicializa el índice SQLite)
• Node.js 22 o posterior

---

Configuración mediante Filamental

La forma más fácil de conectarse es a través de la aplicación:

1. Abre Filamental y ve a Configuración > Integraciones de IA
2. Haz clic en Conectar con Claude Desktop
3. Reinicia Claude Desktop

Filamental resuelve todas las rutas automáticamente. El MCP sigue la bóveda que tengas abierta — no se necesita reiniciar al cambiar de mundos.

---

Configuración manual

Instalar globalmente:

npm install -g filamental-mcp

Luego añade a tu claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "filamental": {
      "command": "node",
      "args": [
        "--no-warnings",
        "/absolute/path/to/node_modules/filamental-mcp/dist/index.js"
      ]
    }
  }
}

No se necesita el argumento --vault. El servidor lee la bóveda activa de Filamental automáticamente y se reconecta cuando cambias de mundos. Para fijar una bóveda específica (por ejemplo, para pruebas), pasa --vault <absolute-path> explícitamente.

Claude Code

Añade un .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "filamental": {
      "command": "npx",
      "args": [
        "filamental-mcp",
        "--vault",
        "/absolute/path/to/your/vault"
      ]
    }
  }
}

---

Herramientas

Lectura

Herramienta	Descripción
get_vault_info	Conteos de nodos y aristas, más nombres de tipos de entidad y conector
list_node_types	Configuración completa de tipos de entidad para esta bóveda
list_connector_types	Configuración completa de tipos de conector para esta bóveda
search_nodes	Búsqueda de texto completo en nombres de nodos, cuerpos de notas y valores de propiedades
get_node	Registro completo de nodo por UUID
get_connections	Todas las aristas conectadas a un nodo, reportadas desde el punto de vista de ese nodo (ver Dirección de flecha)
get_subgraph	Recorrido BFS desde un nodo raíz hasta N saltos (profundidad máxima 3)

Escritura

Herramienta	Descripción
create_node	Crear un nuevo nodo -- escribe un archivo markdown y actualiza el índice SQLite
update_node	Actualizar un nodo existente; los campos omitidos no cambian
delete_node	Eliminar un nodo y quitarlo del índice
create_edge	Añadir una relación entre dos nodos
delete_edge	Eliminar una relación entre dos nodos

---

Dirección de flecha

El direction de un conector es uno de none, outgoing, incoming o bidirectional. No se acepta nada más, y un valor no reconocido se rechaza en lugar de almacenarse.

En escrituras (create_edge, create_node, update_node) la dirección se indica relativa a source → target: outgoing dibuja la punta de flecha en el destino, incoming la dibuja de vuelta en el origen, bidirectional dibuja ambas, none es una línea simple.

En lecturas (get_connections) la dirección se indica en cambio relativa al nodo sobre el que preguntaste, porque eso es lo que el usuario ve en pantalla:

Campo	Significado
node	El nodo sobre el que preguntaste
other	El nodo en el extremo opuesto
direction	Dónde se dibuja la punta de flecha, visto desde node
stored_on	Qué archivo de nodo contiene la relación

Esta distinción importa. Qué extremo de un conector se almacena como source se decide según el extremo desde el que el usuario arrastró al dibujarlo, y es invisible en el grafo — un conector no dirigido se ve idéntico en cualquier orientación. Así que la misma flecha se lee como outgoing desde un extremo y como incoming desde el otro, y get_connections la invierte por ti. Filtrar con direction: "outgoing" te da aristas cuya flecha apunta hacia afuera del nodo sobre el que preguntaste, nunca aristas que simplemente estén almacenadas con él como source. Una arista bidirectional coincide con ambos filtros outgoing y incoming, ya que genuinamente apunta en ambas direcciones; undirected coincide solo con aristas sin flecha alguna.

Usa stored_on solo si estás editando directamente el archivo Markdown subyacente. No dice nada sobre lo que hace la flecha.

---

Opciones de CLI

filamental-mcp --vault <path>          Use vault at <path>
filamental-mcp --vault <path> --db <path>   Override the SQLite database path (for testing)

---

Cómo funciona

Filamental almacena todos los datos de nodos como archivos Markdown con frontmatter YAML dentro de la carpeta de tu bóveda. También mantiene un índice SQLite (almacenado en el directorio de configuración de tu sistema operativo, no dentro de la bóveda) para búsqueda de texto completo y recorrido de grafos rápidos.

Este servidor abre ese índice SQLite en modo lectura-escritura. Las herramientas de lectura lo consultan directamente. Las herramientas de escritura actualizan tanto el archivo Markdown en disco como el índice SQLite para que la aplicación Filamental vea los cambios de inmediato en la siguiente carga.

---

Compatibilidad

filamental-mcp	Aplicación Filamental	Esquema de BD
0.2.6+	0.3.0 y posteriores (actual)	v6
0.2.0 – 0.2.5	0.2.x	v5

El servidor sigue funcionando incluso con un desajuste de esquema (la BD es un índice desechable, por lo que la mayoría de las operaciones de lectura/escritura toleran la deriva). Si una llamada a una herramienta falla por una razón no relacionada mientras las versiones están desajustadas, el mensaje de error se anota con qué lado actualizar.

---

Limitaciones conocidas

• El binario precompilado (better-sqlite3) es solo para Windows x64. Otras plataformas requieren compilar desde el código fuente.
• La configuración automática mediante la Configuración de Filamental se ha probado en Windows. La resolución de rutas en macOS está incluida pero no probada.

---

Licencia

MIT — Copyright Filamental