Which integrations are available for this server?

Enables semantic search over markdown files to find related notes by meaning, detect duplicates, and search content semantically rather than by keywords. Provides semantic search capabilities for Obsidian vaults, allowing discovery of related notes and duplicate detection across markdown content.

How do I use Semantic Search MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Semantic Search MCP find notes related to machine learning algorithms" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Semantic Search

Semantic search over markdown files. Find related notes by meaning, not just keywords. Detect duplicates before creating new notes.

Supports two server modes:

MCP mode — For Claude Code integration
REST mode — For OpenClaw, scripts, and HTTP clients

Features

Semantic search using sentence-transformers
Duplicate/similar note detection
Auto-updating index with file watcher
Multi-directory support
Inline tag extraction (#tag-name)

Installation

Permanent install (recommended)

# Install as a tool (creates ~/.local/bin/semantic-search-mcp) uv tool install git+https://github.com/bborbe/semantic-search

💡 No GPU? Use CPU-only PyTorch
The default install includes CUDA support (~7GB). If you don't have a dedicated GPU, install with CPU-only PyTorch to save ~5GB disk space:
uv tool install --index https://download.pytorch.org/whl/cpu \ git+https://github.com/bborbe/semantic-search
Performance is identical for typical vault sizes — embedding models run fine on CPU.

One-off usage

# Run directly with uvx (no install needed) uvx --from git+https://github.com/bborbe/semantic-search semantic-search-mcp serve

From PyPI (when published)

pip install semantic-search-mcp

Server Modes

MCP Mode (for Claude Code)

claude mcp add -s project semantic-search \ --env CONTENT_PATH=/path/to/vault \ -- \ uvx --from git+https://github.com/bborbe/semantic-search semantic-search-mcp serve

Tools available:

search_related(query, top_k=5) — Find semantically related notes
check_duplicates(file_path) — Detect duplicate/similar notes

REST Mode (for OpenClaw/HTTP)

# Start server CONTENT_PATH=/path/to/vault semantic-search-mcp serve --mode rest --port 8321 # Or with uvx CONTENT_PATH=/path/to/vault uvx --from git+https://github.com/bborbe/semantic-search \ semantic-search-mcp serve --mode rest --port 8321

Endpoints:

Endpoint	Method	Description
`/search?q=...&top_k=5`	GET	Semantic search
`/duplicates?file=...&threshold=0.85`	GET	Find duplicate notes
`/health`	GET	Health check with index stats
`/reindex`	GET/POST	Force index rebuild

Example queries:

# Search curl 'http://localhost:8321/search?q=kubernetes+deployment' # Find duplicates curl 'http://localhost:8321/duplicates?file=notes/my-note.md' # Health check curl 'http://localhost:8321/health'

CLI Commands

One-shot commands without running a server:

# Search CONTENT_PATH=/path/to/vault semantic-search-mcp search "kubernetes deployment" # Find duplicates CONTENT_PATH=/path/to/vault semantic-search-mcp duplicates path/to/note.md

Configuration

Environment Variables

Variable	Description	Default
`CONTENT_PATH`	Directory to index (comma-separated for multiple)	`./content`
`LOG_LEVEL`	Logging level (DEBUG, INFO, WARNING, ERROR)	`INFO`

Multiple Directories

Index multiple directories by separating paths with commas:

CONTENT_PATH=/path/to/vault1,/path/to/vault2,/path/to/docs

All directories are indexed together and searched as one unified index.

How It Works

First run downloads a small embedding model (~90MB) and indexes your markdown files (<1s for typical vaults). The index auto-updates when files change via filesystem watcher.

Indexed Content

Each markdown file is indexed with weighted components:

Component	Weight	Notes
Filename	3x
Frontmatter `title`	3x
Frontmatter `tags`	2x	Merged with inline tags
Frontmatter `aliases`	2x
Inline tags (`#tag`)	2x	Extracted from body
First H1 heading	2x
Body content	1x	First 500 words

Development

# Clone git clone https://github.com/bborbe/semantic-search cd semantic-search # Install dev dependencies make install # Run checks make check # Run tests make test