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:

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

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