README.md•12.5 kB
# 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:**
```bash
git clone https://github.com/msdanyg/smart-connections-mcp.git
cd smart-connections-mcp
```
2. **Install dependencies:**
```bash
npm install
```
3. **Build the TypeScript project:**
```bash
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:
```json
{
"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:**
```typescript
{
"note_path": "MyNote.md",
"threshold": 0.7,
"limit": 5
}
```
**Returns:**
```json
[
{
"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:**
```typescript
{
"note_path": "MyNote.md",
"depth": 2,
"threshold": 0.7
}
```
**Returns:**
```json
{
"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:**
```typescript
{
"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:**
```typescript
{
"note_path": "MyNote.md",
"include_blocks": ["#Introduction", "#Main Points"]
}
```
**Returns:**
```json
{
"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:**
```json
{
"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
```bash
npm run build
```
### Watch Mode
```bash
npm run watch
```
### Run Locally
```bash
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](https://obsidian.md/)
- Integrates with [Smart Connections](https://github.com/brianpetro/obsidian-smart-connections) plugin
- Uses [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic