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. Supports both:

Query-based search: Uses Ollama to generate embeddings for search queries, enabling true semantic search
Keyword fallback: Token-based matching when Ollama is unavailable

🕸️ 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)
Optional: Ollama with an embedding model for semantic query search (e.g., nomic-embed-text-v2-moe)

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",
        "OLLAMA_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "nomic-embed-text-v2-moe:latest",
        "CACHE_DIR": "/ABSOLUTE/PATH/TO/.smart-env/query-cache"
      }
    }
  }
}
```
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
Optional Ollama Configuration (for semantic query search):
- OLLAMA_URL: URL of your Ollama instance (default: http://localhost:11434)
- OLLAMA_MODEL: Embedding model to use (must match your vault embeddings)
- CACHE_DIR: Directory for query embedding cache (improves performance)

Optional: Setup Ollama for Semantic Query Search

To enable true semantic search for text queries (recommended):

# Install Ollama (if not already installed)
# Visit: https://ollama.ai

# Pull the embedding model that matches your vault
# For nomic embeddings (768 dimensions):
ollama pull nomic-embed-text-v2-moe:latest

# For default Smart Connections (384 dimensions):
ollama pull TaylorAI/bge-micro-v2

# Start Ollama (usually runs automatically)
ollama serve

Without Ollama, the server will fall back to keyword-based search (less accurate).

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. Uses semantic search via Ollama if available, falls back to keyword matching otherwise.

Parameters:

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

Example:

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

How it works:

With Ollama: Generates query embedding → cosine similarity search (cached for performance)
Without Ollama: Token-based keyword matching (less accurate but functional)

Returns:

[
  {
    "path": "ProjectNote.md",
    "similarity": 0.78,
    "blocks": ["#Overview", "#Timeline"]
  }
]

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() → searchByEmbedding()           │   │
│  │  - searchByKeyword() (fallback)                    │   │
│  └────────────┬───────────────────────┬─────────────────┘   │
│               │                       │                     │
│  ┌────────────▼────────────────┐  ┌──▼──────────────────┐  │
│  │  ollama-client.ts           │  │  embedding-utils.ts │  │
│  │  - Generate query embeddings│  │  - cosineSimilarity │  │
│  │  - Disk-based LRU cache     │  │  - findNeighbors    │  │
│  │  - Health check & fallback  │  └─────────────────────┘  │
│  └────────────┬─────────────────┘                          │
│               │                                             │
│               │ HTTP                                        │
│               │                                             │
│  ┌────────────▼────────────────────────────────────────┐   │
│  │  smart-connections-loader.ts (Data Access)         │   │
│  │  - Load .smart-env/smart_env.json                  │   │
│  │  - Load .smart-env/multi/*.ajson embeddings        │   │
│  │  - Read note content from vault                    │   │
│  └────────────────┬────────────────────────────────────┘   │
└───────────────────┼─────────────────────────────────────────┘
                    │
    ┌───────────────┼───────────────┐
    │               │               │
┌───▼──────┐  ┌─────▼─────────┐  ┌─▼────────────────────┐
│  Ollama  │  │ File System   │  │ .smart-env/          │
│  Server  │  │ (vault *.md)  │  │ query-cache/         │
│  :11434  │  │               │  │ embeddings.json      │
└──────────┘  └───────────────┘  └──────────────────────┘

Technical Details

Embedding Models

The server supports multiple embedding models depending on your Smart Connections configuration:

Model	Dimensions	Notes
TaylorAI/bge-micro-v2	384	Default Smart Connections model
nomic-embed-text-v2-moe	768	Higher quality, recommended for Ollama
Custom models	Variable	Auto-detected from vault embeddings

Important: Your OLLAMA_MODEL must match the embedding model used in your Obsidian vault.

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
query-cache/embeddings.json: Cached query embeddings (auto-created)

Performance

Operation	With Ollama Cache	Without Cache	Keyword Fallback
Load time	2-5s	2-5s	2-5s
First query search	~500-800ms	~500-800ms	~100-200ms
Cached query	<50ms	N/A	~100-200ms
Memory usage	~30-40MB	~20-30MB	~20-30MB

Query Cache Benefits:

LRU eviction (max 1000 entries)
Disk-persisted across restarts
Significantly faster repeated searches
Automatic cleanup of old entries

Similarity Metric

Cosine similarity for all vector comparisons
Range: 0.0 (unrelated) to 1.0 (identical)
Configurable threshold per query

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 (async)
│   ├── ollama-client.ts            # Ollama integration & caching (NEW)
│   ├── 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

Ollama-related issues

"Ollama unavailable, using keyword fallback"

Normal behavior - server continues to work with keyword matching
To enable semantic search:
1. Install Ollama: https://ollama.ai
2. Pull embedding model: ollama pull nomic-embed-text-v2-moe
3. Verify Ollama is running: curl http://localhost:11434/api/tags
4. Restart Claude Desktop

"Embedding dimension mismatch"

Your OLLAMA_MODEL doesn't match your vault embeddings
Check your vault's model: Look in .smart-env/smart_env.json → "embed_model"
Update OLLAMA_MODEL in your MCP configuration to match
Common combinations:
- Vault uses TaylorAI/bge-micro-v2 → Ollama model: TaylorAI/bge-micro-v2
- Vault uses nomic-embed-text-v2-moe → Ollama model: nomic-embed-text-v2-moe:latest

Slow query performance

First queries are slower (~500-800ms) while building cache
Subsequent identical queries should be <50ms
Check cache file exists: .smart-env/query-cache/embeddings.json
Cache is LRU with max 1000 entries - old entries auto-removed

License

MIT

Author

Daniel Glickman

Acknowledgments

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

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
dist		dist
src		src
.gitignore		.gitignore
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
RESTART-INSTRUCTIONS.md		RESTART-INSTRUCTIONS.md
TESTING.md		TESTING.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
package-lock.json		package-lock.json
package.json		package.json
test-all-tools.mjs		test-all-tools.mjs
test-embeddings.mjs		test-embeddings.mjs
test-mcp-server.mjs		test-mcp-server.mjs
test-search.mjs		test-search.mjs
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

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 Models

Data Format

Performance

Similarity Metric

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

Ollama-related issues

"Ollama unavailable, using keyword fallback"

"Embedding dimension mismatch"

Slow query performance

License

Author

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. `get_similar_notes`

2. `get_connection_graph`

3. `search_notes`

4. `get_embedding_neighbors`

5. `get_note_content`

6. `get_stats`

Packages