Personal Semantic Search MCP

A Model Context Protocol (MCP) server that enables semantic search over your local notes and documents. Built for use with Claude Code and other MCP-compatible clients.

Features

• Semantic Search: Find notes by meaning, not just keywords
• Multiple File Types: Supports Markdown, Python, HTML, JSON, CSV, and plain text
• Smart Chunking: Preserves document structure with header hierarchy
• Fast Local Embeddings: Uses all-MiniLM-L6-v2 (384 dimensions, runs on CPU)
• ChromaDB Storage: Persistent vector database with incremental indexing
• File Watching: Optional real-time re-indexing on file changes

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Claude Code    │────▶│   MCP Server     │────▶│   ChromaDB      │
│  (MCP Client)   │     │   (FastMCP)      │     │   (Vectors)     │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │ Sentence-        │
                        │ Transformers     │
                        │ (Embeddings)     │
                        └──────────────────┘

Installation

# Clone the repository
git clone https://github.com/Ethan2298/personal-semantic-search-mcp.git
cd personal-semantic-search-mcp

# Create virtual environment
python -m venv .venv

# Activate (Windows)
.venv\Scripts\activate

# Activate (Unix/macOS)
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Configuration

Claude Code Setup

Add to your ~/.claude/.mcp.json:

{
  "mcpServers": {
    "semantic-search": {
      "command": "/path/to/your/.venv/Scripts/python.exe",
      "args": ["/path/to/your/mcp_server.py"]
    }
  }
}

Then enable in ~/.claude/settings.json:

{
  "enabledMcpjsonServers": ["semantic-search"]
}

Usage

MCP Tools (via Claude Code)

Once configured, Claude Code can use these tools:

Tool	Description
search_notes	Semantic search with natural language queries
index_notes	Index or re-index your vault
get_index_stats	Show indexing statistics

CLI Usage

# Index a folder
python search.py index ~/Desktop/Notes

# Search
python search.py query "how to implement authentication"

# Watch for changes (real-time indexing)
python search.py watch ~/Desktop/Notes

# Show statistics
python search.py stats

Module Overview

File	Purpose
mcp_server.py	FastMCP server exposing tools via stdio
search.py	High-level search and indexing API
embedding_engine.py	Sentence-transformer embeddings
vector_store.py	ChromaDB storage and retrieval
text_chunker.py	Document chunking with overlap
file_reader.py	Multi-format text extraction
folder_watcher.py	File system change detection

How It Works

1. File Reading: Extracts text from various formats (Markdown, Python, HTML, etc.)
2. Chunking: Splits documents into ~500 token chunks with 50 token overlap, preserving header hierarchy
3. Embedding: Converts chunks to 384-dimensional vectors using all-MiniLM-L6-v2
4. Storage: Stores vectors in ChromaDB with metadata (file path, headers, timestamps)
5. Search: Embeds queries and finds nearest neighbors by cosine similarity

Performance Notes

• First startup: ~10 seconds (loading sentence-transformers model)
• Indexing speed: ~100 documents/minute (depends on size)
• Search latency: <100ms after warmup
• Model size: ~80MB (downloaded on first run)

Requirements

• Python 3.10+
• ~500MB disk space (model + dependencies)
• Works on CPU (no GPU required)

License

MIT