个人语义搜索MCP
一个模型上下文协议（MCP）服务器，支持对本地笔记和文档进行语义搜索。专为与Claude Code和其他MCP兼容客户端一起使用而构建。
特性
- 语义搜索：按含义查找笔记，而不仅仅是关键字
- 多种文件类型：支持Markdown、Python、HTML、JSON、CSV和纯文本
- 智能分块：保留具有页眉层次结构的文档结构
- 快速本地嵌入：用途
all-MiniLM-L6-v2（384个维度，在CPU上运行） - ChromaDB存储：具有增量索引的持久矢量数据库
- 文件监视：可选择对文件更改进行实时重新索引
建筑
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Claude Code │────▶│ MCP Server │────▶│ ChromaDB │
│ (MCP Client) │ │ (FastMCP) │ │ (Vectors) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
┌──────────────────┐
│ Sentence- │
│ Transformers │
│ (Embeddings) │
└──────────────────┘安装
# 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配置
Claude代码设置
添加到您的 ~/.claude/.mcp.json:
{
"mcpServers": {
"semantic-search": {
"command": "/path/to/your/.venv/Scripts/python.exe",
"args": ["/path/to/your/mcp_server.py"]
}
}
}然后启用 ~/.claude/settings.json:
{
"enabledMcpjsonServers": ["semantic-search"]
}用法
MCP工具（通过克劳德代码）
配置后，Claude Code可以使用这些工具：
| 工具 | 说明 |
|---|---|
search_notes | 基于自然语言查询的语义搜索 |
index_notes | 索引或重新索引您的保险库 |
get_index_stats | 显示索引统计信息 |
CLI使用情况
# 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模块概述
| 文件 | 目的 |
|---|---|
mcp_server.py | FastMCP服务器通过stdio公开工具 |
search.py | 高级搜索和索引API |
embedding_engine.py | 句子转换器嵌入 |
vector_store.py | ChromaDB存储和检索 |
text_chunker.py | 重叠文档分块 |
file_reader.py | 多格式文本提取 |
folder_watcher.py | 文件系统更改检测 |
运作原理
- 文件读取：从各种格式（Markdown、Python、HTML等）中提取文本
- 分块：将文档拆分为约500个令牌块，重叠50个令牌，保留标头层次结构
- 嵌入：使用将块转换为384维向量
all-MiniLM-L6-v2 - 存储：将向量与元数据（文件路径、标头、时间戳）一起存储在ChromaDB中
- 搜索：嵌入查询并通过余弦相似度查找最近邻
业绩说明
- 首次启动：~10秒（加载句子转换器模型）
- 索引速度：约100个文档/分钟（取决于大小）
- 搜索延迟：预热后\<100ms
- 模型尺寸：~80MB（首次运行时下载）
需求
- Python 3.10+
- ~500MB磁盘空间（型号+依赖关系）
- 在CPU上工作（不需要GPU）
许可证
麻省理工学院