home / mcp / personal semantic search mcp server
Provides semantic search over local notes and documents via an MCP client.
Configuration
View docs{
"mcpServers": {
"ethan2298-personal-semantic-search-mcp": {
"command": "/path/to/your/.venv/Scripts/python.exe",
"args": [
"/path/to/your/mcp_server.py"
]
}
}
}You can set up a local semantic search MCP server to query your notes and documents by meaning. It uses a lightweight embedding model, stores vectors locally, and works with MCP clients to let you search across Markdown, code, HTML, JSON, CSV, and plain text files quickly and offline.
You run a local MCP server and connect a compatible MCP client to it. The server indexes your notes, converts each document into vector representations, and lets you perform semantic searches that understand intent rather than just keywords. Use it to index a vault of notes, then ask natural language questions like “what summarizes my project milestones?” or “how do I implement authentication?”.
In Claude Code, enable the semantic search MCP server as an available tool. Once enabled, you can run these high‑level actions from the client: search_notes to run natural language queries, index_notes to index or re-index your vault, and get_index_stats to view indexing metrics.
From the command line, you can also index folders, perform queries, watch for real-time updates, and inspect statistics. These actions help you keep your local notes searchable and up to date.
Prerequisites you need before starting: Python 3.10 or later and a working CPU environment. You may also want a Python virtual environment to isolate dependencies.
Steps to install and run the MCP server locally:
# Clone the project
git clone https://github.com/Ethan2298/personal-semantic-search-mcp.git
cd personal-semantic-search-mcp
# Create a virtual environment
python -m venv .venv
# Activate the virtual environment
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
# Install dependencies
pip install -r requirements.txtConfigure the MCP client integration for Claude Code by specifying the MCP server that runs locally. The following setup runs the server using the Python interpreter inside your virtual environment and the main MCP script.
{
"mcpServers": {
"semantic-search": {
"command": "/path/to/your/.venv/Scripts/python.exe",
"args": ["/path/to/your/mcp_server.py"]
}
}
}After configuring the MCP client, you will enable the semantic-search server in the client settings. No external endpoints are required; everything runs on your local machine. The server will index files, create compact token chunks, and store vectors in a local vector store for fast retrieval.
Tools available through Claude Code for this MCP server include search_notes, index_notes, and get_index_stats. Use index_notes to index or update your vault, search_notes for semantic queries, and get_index_stats to review indexing information.
If indexing is slow, verify your disk space and CPU availability. The first startup may take a moment as the sentence-transformers model loads. Ensure the virtual environment is activated when you run the server. If you encounter issues with file formats, confirm that your documents include text content that can be extracted (Markdown, Python, HTML, JSON, CSV, or plain text).
Semantic search with natural language queries that returns relevant notes based on meaning rather than exact keyword matches.
Index or re-index your vault to update the vector store with new or changed documents.
Display indexing statistics such as document count and vector store metrics.