Smart Connections MCP Server

A Model Context Protocol (MCP) server that provides semantic search and knowledge graph capabilities for Obsidian vaults using Smart Connections embeddings.

Overview

This MCP server allows Claude (and other MCP clients) to:

• Search semantically through your Obsidian notes using pre-computed embeddings
• Find similar notes based on content similarity
• Build connection graphs showing how notes are related
• Query by embedding vectors for advanced use cases
• Access note content with block-level granularity

Features

🔍 Semantic Search

Uses the embeddings generated by Obsidian's Smart Connections plugin to perform fast, accurate semantic searches across your entire vault.

🕸️ Connection Graphs

Builds multi-level connection graphs showing how notes are related through semantic similarity, helping discover hidden relationships in your knowledge base.

📊 Vector Similarity

Direct access to embedding-based similarity calculations using cosine similarity on 384-dimensional vectors (TaylorAI/bge-micro-v2 model).

📝 Content Access

Retrieve full note content or specific sections/blocks with intelligent extraction based on Smart Connections block mappings.

Installation

Prerequisites

• Node.js 18 or higher
• An Obsidian vault with Smart Connections plugin installed and embeddings generated
• Claude Desktop (or another MCP client)

Setup

1. Clone the repository:

   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
   

4. Configure Claude Desktop:

   Edit your Claude Desktop configuration file:

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

   Add the following to the mcpServers section:

   {
     "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"
         }
       }
     }
   }
   

   Important: Replace the paths with your actual paths:

   • Update the args path to point to your built index.js file
   • Update SMART_VAULT_PATH to your Obsidian vault path

5. Restart Claude Desktop

   The MCP server will automatically start when Claude Desktop launches.

Available Tools

1. get_similar_notes

Find notes semantically similar to a given note.

Parameters:

• note_path (string, required): Path to the note (e.g., "Note.md" or "Folder/Note.md")
• threshold (number, optional): Similarity threshold 0-1, default 0.5
• limit (number, optional): Maximum results, default 10

Example:

{
  "note_path": "MyNote.md",
  "threshold": 0.7,
  "limit": 5
}

Returns:

[
  {
    "path": "RelatedNote.md",
    "similarity": 0.85,
    "blocks": ["#Overview", "#Key Points", "#Details"]
  }
]

2. get_connection_graph

Build a multi-level connection graph showing how notes are semantically connected.

Parameters:

• note_path (string, required): Starting note path
• depth (number, optional): Graph depth (levels), default 2
• threshold (number, optional): Similarity threshold 0-1, default 0.6
• max_per_level (number, optional): Max connections per level, default 5

Example:

{
  "note_path": "MyNote.md",
  "depth": 2,
  "threshold": 0.7
}

Returns:

{
  "path": "MyNote.md",
  "depth": 0,
  "similarity": 1.0,
  "connections": [
    {
      "path": "RelatedNote.md",
      "depth": 1,
      "similarity": 0.82,
      "connections": [...]
    }
  ]
}

3. search_notes

Search notes using a text query (keyword-based, ranked by relevance).

Parameters:

• query (string, required): Search query text
• limit (number, optional): Maximum results, default 10
• threshold (number, optional): Relevance threshold 0-1, default 0.5

Example:

{
  "query": "project management",
  "limit": 5
}

4. get_embedding_neighbors

Find nearest neighbors for a given embedding vector (advanced use).

Parameters:

• embedding_vector (number[], required): 384-dimensional vector
• k (number, optional): Number of neighbors, default 10
• threshold (number, optional): Similarity threshold 0-1, default 0.5

5. get_note_content

Retrieve full note content with optional block extraction.

Parameters:

• note_path (string, required): Path to the note
• include_blocks (string[], optional): Specific block headings to extract

Example:

{
  "note_path": "MyNote.md",
  "include_blocks": ["#Introduction", "#Main Points"]
}

Returns:

{
  "content": "# Full note content...",
  "blocks": {
    "#Introduction": "Content of this section...",
    "#Main Points": "Content of this section..."
  }
}

6. get_stats

Get statistics about the knowledge base.

Parameters: None

Returns:

{
  "totalNotes": 137,
  "totalBlocks": 1842,
  "embeddingDimension": 384,
  "modelKey": "TaylorAI/bge-micro-v2"
}

Usage Examples

Once configured, you can ask Claude to use these tools naturally:

• "Find notes similar to my project planning document"
• "Show me a connection graph starting from my main research note"
• "Search my notes for information about [your topic]"
• "What's in my note about [topic]?"
• "Give me stats about my knowledge base"

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Claude Desktop                         │
│                    (MCP Client)                             │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          │ MCP Protocol (stdio)
                          │
┌─────────────────────────▼───────────────────────────────────┐
│              Smart Connections MCP Server                   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  index.ts (MCP Server + Tool Handlers)             │   │
│  └────────────────┬────────────────────────────────────┘   │
│                   │                                         │
│  ┌────────────────▼────────────────────────────────────┐   │
│  │  search-engine.ts (Semantic Search Logic)          │   │
│  │  - getSimilarNotes()                               │   │
│  │  - getConnectionGraph()                            │   │
│  │  - searchByQuery()                                 │   │
│  └────────────────┬────────────────────────────────────┘   │
│                   │                                         │
│  ┌────────────────▼────────────────────────────────────┐   │
│  │  smart-connections-loader.ts (Data Access)         │   │
│  │  - Load .smart-env/smart_env.json                  │   │
│  │  - Load .smart-env/multi/*.ajson embeddings        │   │
│  │  - Read note content from vault                    │   │
│  └────────────────┬────────────────────────────────────┘   │
│                   │                                         │
│  ┌────────────────▼────────────────────────────────────┐   │
│  │  embedding-utils.ts (Vector Math)                  │   │
│  │  - cosineSimilarity()                              │   │
│  │  - findNearestNeighbors()                          │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          │ File System Access
                          │
┌─────────────────────────▼───────────────────────────────────┐
│            Obsidian Vault + .smart-env/                     │
│  - smart_env.json (config)                                  │
│  - multi/*.ajson (embeddings for 137 notes)                 │
│  - *.md (markdown note files)                               │
└─────────────────────────────────────────────────────────────┘

Technical Details

Embedding Model

• Model: TaylorAI/bge-micro-v2
• Dimensions: 384
• Similarity Metric: Cosine similarity

Data Format

The server reads from Obsidian's Smart Connections .smart-env/ directory:

• smart_env.json: Configuration and model settings
• multi/*.ajson: Per-note embeddings and block mappings

Performance

• Load time: ~2-5 seconds for 137 notes
• Search: Near-instant (<50ms) using pre-computed embeddings
• Memory: ~20-30MB for embeddings + note index

Development

Build

npm run build

Watch Mode

npm run watch

Run Locally

export SMART_VAULT_PATH="/path/to/your/vault"
npm run dev

Project Structure

smart-connections-mcp/
├── src/
│   ├── index.ts                    # MCP server & tool handlers
│   ├── search-engine.ts            # Semantic search logic
│   ├── smart-connections-loader.ts # Data loading
│   ├── embedding-utils.ts          # Vector math utilities
│   └── types.ts                    # TypeScript type definitions
├── dist/                           # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Troubleshooting

"Smart Connections directory not found"

• Ensure your vault has the Smart Connections plugin installed
• Verify embeddings have been generated (check .smart-env/multi/ directory)
• Check that SMART_VAULT_PATH points to the correct vault

"Configuration file not found"

• Run Smart Connections in Obsidian at least once to generate configuration
• Check for .smart-env/smart_env.json in your vault

"No embeddings found for note"

• Some notes may not have embeddings if they're too short (< 200 chars)
• Re-run Smart Connections embedding generation in Obsidian

Server not appearing in Claude Desktop

• Verify the configuration file syntax (JSON must be valid)
• Check the file paths are absolute paths, not relative
• Restart Claude Desktop completely
• Check Claude Desktop logs for error messages

License

MIT

Author

Daniel Glickman

Acknowledgments

• Built for use with Obsidian
• Integrates with Smart Connections plugin
• Uses Model Context Protocol by Anthropic