smart-connections-mcp by msdanyg - MCP Server

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

Clone the repository:

git clone https://github.com/msdanyg/smart-connections-mcp.git
cd smart-connections-mcp

Install dependencies:
```
npm install
```
Build the TypeScript project:
```
npm run build
```
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
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

msdanyg/smart-connections-mcp

Smart Connections MCP Server

Overview

Features

🔍 Semantic Search

🕸️ Connection Graphs

📊 Vector Similarity

📝 Content Access

Installation

Prerequisites

Setup

Available Tools

1. get_similar_notes

2. get_connection_graph

3. search_notes

4. get_embedding_neighbors

5. get_note_content

6. get_stats

Usage Examples

Architecture

Technical Details

Embedding Model

Data Format

Performance

Development

Build

Watch Mode

Run Locally

Project Structure

Troubleshooting

"Smart Connections directory not found"

"Configuration file not found"

"No embeddings found for note"

Server not appearing in Claude Desktop

License

Author

Acknowledgments

1. `get_similar_notes`

2. `get_connection_graph`

3. `search_notes`

4. `get_embedding_neighbors`

5. `get_note_content`

6. `get_stats`