Semantic Search MCP
语义搜索
对 Markdown 文件进行语义搜索。通过含义而非仅仅关键词查找相关笔记。在创建新笔记前检测重复内容。
支持两种服务器传输方式：
stdio MCP — 用于 Claude Code 集成（每个会话一个进程）
HTTP — 在一个端口上同时提供 MCP-over-HTTP 和 REST 服务；所有客户端共享一个预热进程
功能
使用 sentence-transformers 进行语义搜索
重复/相似笔记检测
通过文件监视器自动更新索引
支持多目录
内联标签提取 (
#tag-name)
安装
仅 CPU 安装 — 推荐用于 macOS（任何 Mac，Apple Silicon 或 Intel）以及 没有 NVIDIA GPU 的 Linux/Windows。可节省约 5GB 的 CUDA 二进制文件。在 macOS 上，Apple GPU (MPS) 仍会通过 PyTorch 内置的 MPS 后端自动检测并使用 —— “CPU” 标签仅指没有 CUDA，而非运行时不使用计算设备。
uv tool install --index https://download.pytorch.org/whl/cpu \
git+https://github.com/bborbe/semantic-searchCUDA 安装 — 仅适用于 带有专用 NVIDIA GPU 的 Linux/Windows。不适用于 macOS（Mac 不支持 NVIDIA CUDA）。
uv tool install git+https://github.com/bborbe/semantic-search升级
uv tool upgrade semantic-search服务器模式
stdio MCP (每个会话的 Claude Code)
每个 Claude Code 会话启动一个进程。简单，但每个会话都会加载其自己的约 400 MB–1 GB 的模型副本。
claude mcp add -s project semantic-search \
--env CONTENT_PATH=/path/to/vault \
-- \
uvx --from git+https://github.com/bborbe/semantic-search semantic-search-mcp可用工具：
search_related(query, top_k=5)— 查找语义相关的笔记check_duplicates(file_path)— 检测重复/相似的笔记
HTTP (所有客户端共享)
单个长期运行的进程在 /mcp 提供 MCP-over-HTTP，并在 /search、/duplicates、/health、/reindex 提供 REST 服务。所有 Claude Code 会话和 REST 客户端共享一个预热索引器。
CONTENT_PATH=/path/to/vault semantic-search-http --host 127.0.0.1 --port 8321通过 MCP 配置将 Claude Code 指向它：
{
"mcpServers": {
"semantic-search": {
"type": "http",
"url": "http://127.0.0.1:8321/mcp"
}
}
}REST 端点：
端点 | 方法 | 描述 |
| POST | MCP-over-HTTP (Claude Code) |
| GET | 语义搜索 |
| GET | 查找重复笔记 |
| GET | 带有索引统计信息的健康检查 |
| GET/POST | 强制重建索引 |
查询示例：
# Search
curl 'http://127.0.0.1:8321/search?q=kubernetes+deployment'
# Find duplicates
curl 'http://127.0.0.1:8321/duplicates?file=notes/my-note.md'
# Health check
curl 'http://127.0.0.1:8321/health'后台运行
对于生产环境的使用，请将 semantic-search-http 作为后台服务运行，以便每个 Claude Code 会话（以及任何 REST 客户端）共享一个预热进程。
平台 | 指南 |
macOS (launchd) | |
Linux (systemd) |
快速示例 (macOS)：
launchctl load ~/Library/LaunchAgents/com.github.bborbe.semantic-search-http.plist快速示例 (Linux)：
systemctl --user enable --now semantic-search-http.serviceCLI 命令
无需运行服务器的一次性命令：
# Search
CONTENT_PATH=/path/to/vault semantic-search search "kubernetes deployment"
# Find duplicates
CONTENT_PATH=/path/to/vault semantic-search duplicates path/to/note.md二进制文件
二进制文件 | 用途 |
| 组合式 HTTP 服务器 — MCP 在 |
| stdio MCP 服务器 — 每个 Claude Code 会话一个。在未设置 HTTP 服务时使用。 |
| 仅 CLI — |
配置
环境变量
变量 | 描述 | 默认值 |
| 要索引的目录（多个目录用逗号分隔） |
|
| 日志级别 (DEBUG, INFO, WARNING, ERROR) |
|
多目录
通过用逗号分隔路径来索引多个目录：
CONTENT_PATH=/path/to/vault1,/path/to/vault2,/path/to/docs所有目录会被一起索引，并作为一个统一的索引进行搜索。
工作原理
首次运行时会下载一个小型嵌入模型（约 90MB）并索引您的 Markdown 文件（典型知识库耗时 <1s）。当文件通过文件系统监视器发生更改时，索引会自动更新。
索引内容
每个 Markdown 文件都使用加权组件进行索引：
组件 | 权重 | 备注 |
文件名 | 3x | |
Frontmatter | 3x | |
Frontmatter | 2x | 与内联标签合并 |
Frontmatter | 2x | |
内联标签 ( | 2x | 从正文中提取 |
第一个 H1 标题 | 2x | |
正文内容 | 1x | 前 500 个单词 |
开发
# Clone
git clone https://github.com/bborbe/semantic-search
cd semantic-search
# Install dev dependencies
make install
# Run checks
make check
# Run tests
make test许可证
BSD 2-Clause License — 参见 LICENSE。
This server cannot be installed
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Appeared in Searches
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/bborbe/semantic-search'
If you have feedback or need assistance with the MCP directory API, please join our Discord server