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:
接入你的智能体
从发布者处安装。不是 PlugMCP 端点。
远程 URL 还是本机命令? 两种安装方式的区别
来自发布者
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
工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式,而不是 PlugMCP 代理。
此记录未列出必需的环境变量。
Smart Connections 通过 stdio 在本地运行。
上次检查时间:2026-10-28。 MCP server that exposes Obsidian Smart Connections vector database to Claude Code via semantic search