Skip to main content
Glama
Ethan2298

Personal Semantic Search MCP

by Ethan2298
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Ethan2298/personal-semantic-search-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server