Smart Connections MCP Server

A security-first MCP server for Smart Connections. Read-only. Path-validated. Auditable.

Exposes Smart Connections embeddings to Claude Code and other MCP clients for semantic search of your Obsidian vault.

# Why This Exists

We needed semantic search of our Obsidian vault from Claude Code. Existing options have problems:

• No path validation - User input passed directly to file operations
• Write access - Some expose mutation tools we don't need
• Heavy dependencies - PyTorch/transformers for what's essentially vector math

This implementation:

• Minimal dependencies - MCP SDK + Transformers.js (for text search)
• Fail-closed security - path validation with realpath, symlink detection
• Auditable - small TypeScript codebase you can actually read

# Features

• Text search - query with plain text, not just note paths
• Semantic search using Smart Connections embeddings
• Local inference - uses Transformers.js (same model as Smart Connections)
• Read-only - no write operations, no shell execution
• Secure - strict path validation, bounded responses
• Offline - works without Obsidian running

# Security Model

| Property | Guarantee |
|- -- -- -- -- -|- -- -- -- -- --|
| Path confinement | All file access validated against vault root |
| No traversal | ../ and symlink attacks blocked |
| Read-only | No write operations exposed |
| Bounded responses | Capped results (50), content length (10KB) |
| Fail closed | Errors deny access, never bypass |
| Audit logging | Security events logged with context |

# Installation

# # Prerequisites

• Node.js 18+
• Obsidian with Smart Connections plugin installed
• Embeddings built (open vault in Obsidian, let Smart Connections index)

# # Setup

git clone https://github.com/gogogadgetbytes/smart-connections-mcp
cd smart-connections-mcp
npm install
npm run build

# # Configure Claude Code

Add to your Claude Code config:

claude mcp add smart-connections \
  -e VAULT_PATH="/path/to/your/obsidian/vault" \
  - - node /path/to/smart-connections-mcp/dist/index.js

Or manually add to ~/.claude.json:

{
  "mcpServers": {
    "smart-connections": {
      "command": "node",
      "args": ["/path/to/smart-connections-mcp/dist/index.js"],
      "env": {
        "VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Restart Claude Code to load the server.

# Usage

Once configured, Claude Code can use these tools:

# # Search by Text

"Search my vault for notes about backup strategies"
→ Uses search_by_text tool

# # Search Similar Notes

"Find notes similar to Topics/Claude_Code.md"
→ Uses search_similar tool

# # Get Note Content

"Show me the content of Topics/Obsidian.md"
→ Uses get_note tool

# # List Indexed Notes

"What notes are indexed in my vault?"
→ Uses list_indexed tool

# Tools

| Tool | Description |
|- -- -- -|- -- -- -- -- -- --|
| search_by_text | Search using freeform text (computes embedding locally) |
| search_similar | Find notes semantically similar to a given note |
| search_by_embedding | Search using a raw embedding vector |
| get_note | Get content of a specific note (path validated) |
| get_model_info | Get embedding model configuration |
| list_indexed | List all indexed notes |

# Configuration

| Variable | Required | Description |
|- -- -- -- -- -|- -- -- -- -- -|- -- -- -- -- -- --|
| VAULT_PATH | Yes | Absolute path to Obsidian vault |

# Limitations

• Single vault - Configure one vault per MCP server instance
• Index from Smart Connections - Note embeddings come from the plugin; text queries are embedded locally
• No write access - By design; use Obsidian for edits
• First run downloads model - ~50MB model cached in ~/.cache/huggingface/

# Development

#  Build
npm run build

#  Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

# Contributing

See CONTRIBUTING.md. Security-focused PRs welcome.

# Security

To report security vulnerabilities, please email gogogadgetcode@proton.me. Do not open public issues for security concerns.

# License

MIT - see LICENSE

# Credits

• Smart Connections by Brian Petro
• Model Context Protocol by Anthropic