Smart Connections

You set up and run the Smart Connections MCP Server to enable semantic search, similarity, and connection graphs over your Obsidian vault. This server exposes powerful tools so you can query notes by content, discover related notes, and navigate knowledge graphs from an MCP client like Claude Desktop.

How to use

Connect your MCP client to the Smart Connections MCP Server and use its tools to explore your Obsidian vault. You can search notes semantically, find notes similar to a given note, build multi-level connection graphs, query by embedding vectors, and retrieve note content with optional block extraction. Interact naturally by asking the client to run tools such as: find notes similar to a document, show a connection graph starting from a main note, search notes by a topic, or retrieve content for a specific note.

How to install

Prerequisites include Node.js 18 or higher and an Obsidian vault with the Smart Connections plugin installed and embeddings generated. You will also need Claude Desktop (or another MCP client).

Step by step installation and setup:

# 1. Clone the MCP server repository and enter the directory
git clone https://github.com/msdanyg/smart-connections-mcp.git
cd smart-connections-mcp

# 2. Install dependencies
npm install

# 3. Build the TypeScript project
npm run build

Configure Claude Desktop for MCP access

You will configure Claude Desktop to start the MCP server when it launches. Update the MCP configuration with the exact paths from your environment.

{
  "mcpServers": {
    "smart-connections": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/smart-connections-mcp/dist/index.js"
      ],
      "env": {
        "SMART_VAULT_PATH": "/ABSOLUTE/PATH/TO/YOUR/OBSIDIAN/VAULT"
      }
    }
  }
}

Run and start the server

Start Claude Desktop. The MCP server will automatically start when Claude Desktop launches, using the configured node command and the path to the built index.js file.

If you need to run the server directly for testing outside Claude Desktop, use the same node command and point to the built entry file, ensuring SMART_VAULT_PATH is set to your Obsidian vault.

Additional configuration notes

The server reads configuration and embeddings from your Obsidian vault’s Smart Connections data. Ensure the vault contains the .smart-env directory with smart_env.json and per-note embedding data under multi/*.ajson, and that the embeddings are generated for the notes you want to query.

Troubleshooting

If the server does not appear in Claude Desktop, verify that the JSON configuration is valid, and that the absolute paths to the index.js file and vault are correct. Restart Claude Desktop and check logs if errors persist.

Available tools

get_similar_notes

Find notes semantically similar to a given note using pre-computed embeddings, with optional threshold and limit.

get_connection_graph

Build a multi-level connection graph showing how notes relate to each other based on embedding similarities.

search_notes

Perform a keyword-based search across notes, ranked by relevance using embeddings.

get_embedding_neighbors

Identify nearest neighbors for a provided 384-dimensional embedding vector.

get_note_content

Retrieve full note content with optional block extraction based on Smart Connections mappings.

get_stats

Return statistics about the knowledge base, including total notes, blocks, and embedding model.