Smart Connections MCP Server
Exposes your Obsidian Smart Connections vector database to Claude Code via Model Context Protocol (MCP).
What This Does
Instead of using text-based Grep, Claude Code can now perform semantic search across your vault:
Potencia tu agente
Instalación del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
Aún no hay una versión empaquetada en el registro. Sigue el README del repositorio.
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDel publicador
Exposes your Obsidian Smart Connections vector database to Claude Code via Model Context Protocol (MCP).
Instead of using text-based Grep, Claude Code can now perform semantic search across your vault:
MCP server that exposes Obsidian Smart Connections vector database to Claude Code via semantic search
Smart Connections Plugin
↓ (creates)
.smart-env/multi/*.ajson
↓ (reads)
This MCP Server
↓ (exposes via)
MCP Protocol
↓ (consumed by)
Claude Code
cd ~/smart-connections-mcp
./install.sh
The script will:
~/.mcp.jsoncurl -LsSf https://astral.sh/uv/install.sh | sh
cd ~/smart-connections-mcp
uv venv
uv pip install -r requirements.txt
Important dependencies:
mcp>=1.0.0 - Official Model Context Protocol SDKsentence-transformers>=2.2.0 - For semantic searchnumpy<2.0.0 - Version 1.x required (2.x breaks compatibility)torch>=2.0.0 and transformers>=4.30.0 - ML dependenciesAdd to ~/.mcp.json:
{
"mcpServers": {
"smart-connections": {
"command": "/Users/YOUR_USERNAME/smart-connections-mcp/.venv/bin/python",
"args": ["/Users/YOUR_USERNAME/smart-connections-mcp/server.py"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}
Note: Use the virtual environment Python, not system Python!
claude mcp list
Expected output:
smart-connections: .venv/bin/python server.py - ✓ Connected
See DEPLOYMENT.md for detailed migration guide.
Quick migration:
# On new machine
git clone https://github.com/dan6684/smart-connections-mcp.git ~/smart-connections-mcp
cd ~/smart-connections-mcp
./install.sh
Important: Keep this MCP server in a separate repository from your Obsidian vault. See DEPLOYMENT.md for rationale and best practices.
If you see timeout issues, see TROUBLESHOOTING.md.
Old way (Grep):
Grep pattern: "self-compassion"
→ Only finds notes with exact word "self-compassion"
New way (Semantic Search):
semantic_search(query: "recognizing self-worth and releasing shame")
→ Finds: Ann Shulgin note ("I am a treasure")
BM playa note ("I am beautiful, playa saved me")
Therapy notes (related concepts)
Like Smart Connections sidebar:
find_related(file_path: "DailyNotes/2025-10-25.md")
→ Returns top 10 semantically similar notes
Build context for complex queries:
get_context_blocks(query: "transformation through embodiment")
→ Returns actual text blocks most relevant to query
→ Claude can use these for grounded answers
.smart-env/multi/*.ajsonsemantic_searchsemantic_search(
query: str, # Natural language query
limit: int = 10, # Max results
min_similarity: float = 0.3 # Threshold
)
Returns:
{
"query": "self-compassion",
"results_count": 5,
"results": [
{
"path": "DailyNotes/2025-08-29.md",
"similarity": 0.87,
"key": "smart_sources:DailyNotes/2025-08-29.md",
"metadata": {"tags": ["#Dream", "#grateful"]}
}
]
}
find_relatedfind_related(
file_path: str, # e.g., "DailyNotes/2025-10-25.md"
limit: int = 10
)
get_context_blocksget_context_blocks(
query: str,
max_blocks: int = 5
)
Returns actual text content (not just paths) for RAG.
See TROUBLESHOOTING.md for detailed debugging guide.
claude mcp listSymptoms: Connection hangs, no response after 30+ seconds
Fixes:
uv pip list | grep numpyOBSIDIAN_VAULT_PATH="/path/to/vault" .venv/bin/python server.py
Error: ImportError: numpy.core.multiarray failed to import
Fix: Reinstall with NumPy 1.x:
uv pip install "numpy<2.0.0" --force-reinstall
.smart-env/multi/ has .ajson filesmin_similarity threshold (try 0.2 instead of 0.3)Update embeddings:
.smart-env/Add new tools:
Edit handle_request() in server.py
MIT - Use freely for personal PKM workflows
MCP server that exposes Obsidian Smart Connections vector database to Claude Code via semantic search
Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
Este registro no indica ninguna variable de entorno obligatoria.
Smart Connections se ejecuta localmente por stdio.
Última comprobación: 2026-10-28. MCP server that exposes Obsidian Smart Connections vector database to Claude Code via semantic search