Vault Knowledge

What vault-knowledge MCP server does

The vault-knowledge MCP server makes selected content from an Obsidian vault available to MCP clients as a read-only typed knowledge graph. It focuses on three operations: semantic concept search, contradiction discovery, and article retrieval. The server is intended for agents that need to inspect an existing body of notes rather than edit, reorganize, or synchronize the vault.

The graph models relationships between concept and connection articles, including a contradicts relation. This lets an agent identify disagreements recorded in the notes instead of only finding text that matches a query. Article retrieval includes frontmatter, the article body, and resolved wikilinks.

How it works

The vault-knowledge MCP server runs locally through stdio, so an MCP client launches it as a subprocess. A synthetic espresso vault is included for an immediate test without configuring a personal data source. To use an existing vault, the process receives the path to an index database and the vault root through environment variables.

search_concepts ranks relevant concept and connection articles semantically. On its first execution, the server downloads the nomic-embed-text-v1.5 model. find_contradictions reads active contradicts edges from the reasoning graph and supports either the full graph or a recent-30-day scope. get_article loads one article by slug and resolves its internal links.

Setup and configuration

The documented installation uses Node.js and the npm package @swins/vault-knowledge-mcp:

{
  "mcpServers": {
    "vault-knowledge": {
      "command": "npx",
      "args": ["-y", "@swins/vault-knowledge-mcp"]
    }
  }
}

Node.js 22.5 or later is required because the server uses the built-in node:sqlite module. The default configuration starts with the included synthetic vault. For a personal vault, set VAULT_DB to the index database path and VAULT_ROOT to the vault directory.

Tools and capabilities

• search_concepts(query, limit=5) returns semantically ranked concept and connection articles.
• find_contradictions(scope='all'|'recent_30d') returns active contradiction edges, either across the graph or from the recent period.
• get_article(slug) returns an article's frontmatter, body, and resolved wikilinks.

Limitations and notes

The vault-knowledge MCP server is read-only and does not provide tools for editing notes or changing the graph. It has no authentication flow and does not require a cloud service. Only content under knowledge/concepts, knowledge/connections, and knowledge/qa is readable. This scope is configured for the server rather than supplied as a request parameter, preventing a client from widening access through a tool call.

The embedding model download occurs on first concept-search use, so that initial operation requires network access to obtain the model. Later searches can use the downloaded model. The README does not document named client-specific integrations; it describes the tools as callable by MCP clients generally.