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

File Reading: Extracts text from various formats (Markdown, Python, HTML, etc.)
Chunking: Splits documents into ~500 token chunks with 50 token overlap, preserving header hierarchy
Embedding: Converts chunks to 384-dimensional vectors using all-MiniLM-L6-v2
Storage: Stores vectors in ChromaDB with metadata (file path, headers, timestamps)
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