Smart Connections MCP server

Smart Connections MCP Server

Give Claude true semantic memory of your Obsidian vault. An MCP server that searches your notes by meaning — reusing the embeddings the Smart Connections Obsidian plugin already generated, and running the same embedding model locally to understand your queries. No cloud calls; your vault never leaves your machine.

What it does

notes and individual sections (blocks), returns similarity-ranked results with content snippets.

• searchnotes** — semantic search across one or many vaults. Matches whole

• getsimilarnotes — notes similar to a given note (stored embeddings).
• getconnectiongraph — walk similarity links outward to map related ideas.
• getnotecontent — read a note, or extract specific blocks.
• listvaults / getstats — what's loaded, counts, models, load errors.

Requirements

generated (v2 tested against Smart Connections 3.x data)

• Node.js 20+
• An Obsidian vault with the Smart Connections plugin installed and embeddings

• An MCP client (Claude Desktop, Claude Code, …)

Setup (Claude Desktop)

Add to claudedesktopconfig.json and restart Claude Desktop:

{
  "mcpServers": {
    "smart-connections": {
      "command": "npx",
      "args": ["-y", "smart-connections-mcp"],
      "env": {
        "SMART_VAULT_PATH": "/path/to/Vault One,/path/to/Vault Two"
      }
    }
  }
}

One vault or several — separate paths with commas.

SMARTVAULTPATHS (plural) is also accepted as an alias for SMARTVAULTPATH and takes precedence over it if both are set.

Claude Code

claude mcp add smart-connections -e SMART_VAULT_PATH="/path/to/vault" -- npx -y smart-connections-mcp

How it works

Smart Connections stores an embedding vector for every note and block in .smart-env/. This server loads those vectors into memory and, when you search, embeds your query with the same model your vault used (downloaded once, ~25MB, runs locally via transformers.js). Results are ranked by cosine similarity. Edits you make in Obsidian are picked up automatically.

If the embedding model can't load (e.g. no network on very first run), or a vault has no embeddings yet, search degrades to literal keyword matching and says so explicitly ("mode": "keyword-fallback" plus a warning naming the cause). When only some vaults fall back, mode stays "semantic", those rows carry "match": "keyword", and they always rank after the true semantic rows.

Migrating from v1

scope, block, snippet, and mode fields.

• getembeddingneighbors was removed.
• search_notes is now genuinely semantic and its response includes vault,

configs work unchanged.

• Everything else is backward compatible; single-vault SMARTVAULTPATH

Development

npm install
npm test              # build + CI-tier tests (no network)
npm run test:live     # + real-model tests (downloads ~25MB once)
npm run smoke -- "/path/to/vault" "your query"

MIT — see LICENSE.