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
mcpServerssection:{ "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
argspath to point to your builtindex.jsfile - Update
SMART_VAULT_PATHto your Obsidian vault path
- macOS:
-
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.5limit(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 pathdepth(number, optional): Graph depth (levels), default 2threshold(number, optional): Similarity threshold 0-1, default 0.6max_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 textlimit(number, optional): Maximum results, default 10threshold(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 vectork(number, optional): Number of neighbors, default 10threshold(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 noteinclude_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 settingsmulti/*.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_PATHpoints 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.jsonin 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