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