Skip to main content
Glama

Smart Connections MCP Server

by dan6684
GitHub
Python
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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:

  • semantic_search: Find notes by meaning, not keywords

  • find_related: Get related notes (like Smart Connections sidebar)

  • get_context_blocks: Get best context for RAG queries

Architecture

Smart Connections Plugin ↓ (creates) .smart-env/multi/*.ajson ↓ (reads) This MCP Server ↓ (exposes via) MCP Protocol ↓ (consumed by) Claude Code

Installation

Quick Install (Recommended)

cd ~/smart-connections-mcp ./install.sh

The script will:

  • ✅ Install UV package manager (if needed)

  • ✅ Create virtual environment

  • ✅ Install all dependencies

  • ✅ Auto-detect your Obsidian vault

  • ✅ Configure ~/.mcp.json

  • ✅ Verify installation

Manual Installation

1. Install UV

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create Virtual Environment and Install Dependencies

cd ~/smart-connections-mcp uv venv uv pip install -r requirements.txt

Important dependencies:

  • mcp>=1.0.0 - Official Model Context Protocol SDK

  • sentence-transformers>=2.2.0 - For semantic search

  • numpy<2.0.0 - Version 1.x required (2.x breaks compatibility)

  • torch>=2.0.0 and transformers>=4.30.0 - ML dependencies

3. Configure Claude Code

Add 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!

4. Verify Installation

claude mcp list

Expected output:

smart-connections: .venv/bin/python server.py - ✓ Connected

Migration to New Machine

See 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.

Troubleshooting

If you see timeout issues, see TROUBLESHOOTING.md.

Usage Examples

Semantic Search

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)

Find Related Notes

Like Smart Connections sidebar:

find_related(file_path: "DailyNotes/2025-10-25.md") → Returns top 10 semantically similar notes

Get Context for RAG

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

How It Works

  1. Reads existing embeddings from .smart-env/multi/*.ajson

  2. No re-indexing needed - uses Smart Connections' work

  3. Same model (BGE-micro-v2) for query encoding

  4. Cosine similarity to rank results

  5. Returns JSON with file paths, similarity scores, metadata

Tools Provided

semantic_search

semantic_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_related

find_related( file_path: str, # e.g., "DailyNotes/2025-10-25.md" limit: int = 10 )

get_context_blocks

get_context_blocks( query: str, max_blocks: int = 5 )

Returns actual text content (not just paths) for RAG.

Performance

  • Initial load: ~2-3 seconds (loads 3,249 embeddings)

  • Query time: ~100-200ms (cosine similarity across all embeddings)

  • Memory: ~50MB (cached embeddings)

Troubleshooting

See

Common Issues

Server Timeout on claude mcp list

Symptoms: Connection hangs, no response after 30+ seconds

Fixes:

  1. Ensure using virtual environment Python (not system Python)

  2. Verify NumPy version is <2.0.0: uv pip list | grep numpy

  3. Check server starts manually:

    OBSIDIAN_VAULT_PATH="/path/to/vault" .venv/bin/python server.py

Import Errors

Error: ImportError: numpy.core.multiarray failed to import

Fix: Reinstall with NumPy 1.x:

uv pip install "numpy<2.0.0" --force-reinstall

No Results Returned

  • Check .smart-env/multi/ has .ajson files

  • Verify Smart Connections is enabled in Obsidian

  • Lower min_similarity threshold (try 0.2 instead of 0.3)

Wrong Results

  • Smart Connections may need to re-index

  • Check embedding model matches (BGE-micro-v2)

  • Restart server to reload embeddings

Development

Update embeddings:

  • Smart Connections auto-updates .smart-env/

  • MCP server reads on startup (restart to refresh)

  • Future: Add file watcher for auto-reload

Add new tools: Edit handle_request() in server.py

License

MIT - Use freely for personal PKM workflows

This server cannot be installed

-
security - not tested
-
license - not tested
-
quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables Claude to perform semantic search across your Obsidian vault using Smart Connections vector database. Provides meaning-based search, related note discovery, and context retrieval for RAG queries instead of basic keyword matching.

  1. What This Does
    1. Architecture
      1. Installation
        1. Quick Install (Recommended)
        2. Manual Installation
        3. Migration to New Machine
        4. Troubleshooting
      2. Usage Examples
        1. Semantic Search
        2. Find Related Notes
        3. Get Context for RAG
      3. How It Works
        1. Tools Provided
          1. semantic_search
          2. find_related
          3. get_context_blocks
        2. Performance
          1. Troubleshooting
            1. Common Issues
          2. Development
            1. License

              New MCP Servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/dan6684/smart-connections-mcp'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server