Smart Connections

What the smart-connections MCP server does

The smart-connections MCP server connects an MCP client to one configured Obsidian vault and its Smart Connections index. It provides semantic retrieval rather than relying only on literal keyword matching, so an agent can search for a concept in freeform language or find notes related to an existing note.

The server is read-only. It does not edit notes, execute shell commands, or expose mutation operations. It also works while Obsidian is not running, provided the vault has already been indexed and the required embedding data is available.

How it works

Smart Connections supplies the embeddings for indexed notes. For a plain-text query, the server computes an embedding locally with Transformers.js and compares it against the available index. Similarity searches can instead start from a note, while callers that already have a vector can use the raw-embedding search tool.

File access is confined to the configured vault root. Paths are resolved and checked before access, with traversal and symlink-based escapes rejected. Results are bounded: searches return no more than 50 results, and note content is limited to 10 KB. Security events are logged with context, and failures deny access rather than bypassing validation.

Setup and configuration

Run the server with Node.js 18 or newer. Install the Smart Connections plugin in Obsidian, open the vault, and allow the plugin to build its embeddings before starting the MCP server.

Clone the repository, install its npm dependencies, and build the TypeScript project:

git clone https://github.com/gogogadgetbytes/smart-connections-mcp
cd smart-connections-mcp
npm install
npm run build

Set VAULT_PATH to the absolute path of the Obsidian vault, then launch dist/index.js through the MCP client's stdio configuration. The server can be added to Claude Code with its MCP command or by placing the node command and environment variable in the client's configuration. On first use, the local text-embedding model downloads approximately 50 MB and is cached under ~/.cache/huggingface/.

Tools and capabilities

The smart-connections MCP server exposes these tools:

• search_by_text embeds a freeform query locally and searches the vault.
• search_similar finds notes semantically related to a specified note.
• search_by_embedding searches with a supplied embedding vector.
• get_note reads a note after validating its path.
• get_model_info reports the embedding model configuration.
• list_indexed lists notes present in the index.

These tools support workflows such as locating notes about a topic, finding related research from a known note, checking which notes are indexed, and retrieving a bounded amount of note content for further processing.

Limitations and notes

Each server instance handles one vault only. Note vectors must come from the Smart Connections plugin, so the vault needs to be indexed before semantic note searches can work. Plain-text searches use the locally downloaded model instead.

The server intentionally has no write capability; edits must be made in Obsidian or another file-management workflow. VAULT_PATH is required, and it must identify the vault the process is allowed to read. The implementation is distributed under the MIT license.