Smart Connections MCP

🚀 Smart Connections MCP Server

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

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

🚀 Quick Start

To get started with the Smart Connections MCP Server, follow these steps:

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.

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

🔧 Technical Details

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.

Security Model

💻 Usage Examples

Once configured, Claude Code can use these tools:

Basic Usage

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

📚 Documentation

Tools

Configuration

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

📄 License

This project is licensed under the MIT License - see LICENSE for details.

Credits

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

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.