使用说明
SearchMCP-人工智能专用网络搜索
通过模型上下文协议进行隐私优先的网络搜索。所有搜索路线 默认情况下为Tor，保护您的查询免受监视。
为什么隐私很重要
每次网络搜索都会揭示你的兴趣、担忧、健康问题、政治 观点，以及更多。这些数据由以下机构收集：
- 互联网服务提供商：您的互联网提供商会看到每个搜索查询
- 大科技：谷歌、微软和其他公司建立了详细的个人资料
- 政府：大规模监控程序收集搜索数据
- 广告商：您的搜索是通过广告来定位您的
SearchMCP通过Tor网络路由所有搜索来保护您， 使查询无法追溯到您。
SearchMCP做什么
SearchMCP既是一个独立的CLI工具，也是一个MCP（模型上下文协议） 服务器，为人工智能助手提供隐私保护的网络搜索功能。 它公开了五个工具：
web_search--通过DuckDuckGo进行全面网络搜索image_search--通过DuckDuckGo进行图片搜索news_search--通过DuckDuckGo搜索新闻文章videos_search--通过DuckDuckGo进行视频搜索books_search--通过DuckDuckGo进行图书搜索
默认情况下，所有通过Tor的交通路线。查询内容从不记录。 隐私验证在启动时运行，以确认您的搜索实际上是 在服务器接受任何请求之前，先通过Tor。
先决条件
1.Tor服务（必填）
Tor必须在本地运行，SearchMCP才能工作。
macOS：
brew install tor
tor # Runs in foreground, or use 'brew services start tor' for background
Linux（Debian/Ubuntu）：
sudo apt install tor
sudo systemctl start tor
sudo systemctl enable tor # Start on boot
Linux（Fedora/RHEL）：
sudo dnf install tor
sudo systemctl start tor
sudo systemctl enable tor
窗户： 下载并运行Tor专家包https://www.torproject.org/download/tor/
替代方案：Tor浏览器
如果您安装了Tor Browser，它会在端口9150上提供Tor代理：
SEARCHMCP_TOR_PROXY=socks5h://127.0.0.1:9150 searchmcp
2.VPN（推荐）
为了进行深度防御，请在Tor旁边使用VPN：
- Mullvad VPN：无需帐户，注重隐私
- ProtonVPN：来自ProtonMail团队
- 总机服务：强有力的隐私政策
先连接到VPN，然后启动Tor。这会向ISP隐藏Tor的使用情况。
安装
SearchMCP被打包为一个标准的Python包，用于安装 searchmcp
命令在系统范围内可用。将其用作独立的CLI工具或对其进行配置
作为Claude、Cursor和其他MCP客户端的MCP服务器。
来自PyPI（推荐）：
# With uv (recommended)
uv add searchmcp
# Or with pip
pip install searchmcp
来源于 紫外线:
# Clone the repository
git clone https://github.com/cspenn/searchmcp.git
cd searchmcp
# Install as a tool (adds `searchmcp` to your PATH)
uv tool install .
替代方案：在项目venv中可编辑安装
如果消费项目有自己的virtualenv，并且您希望对 结账后立即反映：
uv pip install -e /path/to/searchmcp
快速开始
-
启动Tor （见上述先决条件）
-
将SearchMCP作为MCP服务器运行 （适用于克劳德、Cursor等）：
searchmcp serve # or simply: searchmcp或者直接运行一次性CLI搜索：
searchmcp web "privacy tools 2025" searchmcp news "AI regulation" --timelimit w --max-results 5 searchmcp images "Tor network diagram" searchmcp videos "how to use Tor browser" searchmcp books "digital privacy handbook" -
验证隐私状态 在启动输出中：
============================================================ SEARCHMCP - Privacy Mode ENABLED ============================================================ Privacy Checklist: [✓] Tor proxy: socks5h://127.0.0.1:9050 [✓] Tor verified: exit IP 185.220.101.x [✓] Query logging: DISABLED For Maximum Privacy, Also Use: • VPN (layered with Tor for defense in depth) • Privacy browser (Tor Browser, Brave, Firefox with privacy extensions, or LibreWolf) • Encrypted email (ProtonMail, Tutanota, or self-hosted) • Encrypted messaging (Signal, Session, or Matrix) • Privacy-respecting DNS (Quad9, Mullvad DNS, NextDNS)
隐私功能
| 特性 | 默认值 | 描述 |
|---|---|---|
| Tor路由 | ON | 所有搜索都通过Tor进行 |
| 查询日志 | 关闭 | 您的搜索永远不会被记录 |
| DNS泄漏防护 | 开启 | 使用socks5h://协议 |
| 退出验证 | ON | 启动时确认Tor连接 |
CLI 参考
SearchMCP提供六个子命令。跑步 searchmcp 没有子命令
等同于 searchmcp serve.
serve --启动MCP服务器
searchmcp serve [--disable-privacy] [--with-logging]
| 标志 | 描述 |
|---|---|
--disable-privacy |
禁用Tor路由（不推荐） |
--with-logging |
在日志中启用查询内容以进行调试 |
示例：
# Default: Maximum privacy
searchmcp serve
# Debugging with query logging (use cautiously)
searchmcp serve --with-logging
# Disable privacy mode (not recommended)
searchmcp serve --disable-privacy
搜索子命令
所有五个搜索子命令共享相同的标志面：
searchmcp web QUERY [options]
searchmcp news QUERY [options]
searchmcp images QUERY [options]
searchmcp videos QUERY [options]
searchmcp books QUERY [options]
| 标志 | 默认值 | 描述 |
|---|---|---|
--max-results N |
10 | 要返回的结果数（1-100） |
--region R |
wt-wt |
地区代码(wt-wt =全球；例如 us-en, uk-en) |
--safesearch S |
moderate |
安全过滤器： off, moderate，或 strict |
--timelimit T |
（无） | 时间窗口： d （天）， w （周）， m （月）， y （年） |
--backend B |
auto |
后端引擎： auto, all，或以名称/逗号分隔的列表 |
--page P |
1 | 结果页码（1-100） |
--disable-privacy |
关闭 | 禁用Tor路由（不推荐） |
--with-logging |
off | 记录查询内容（谨慎使用） |
--json |
off | 输出原始JSON而不是格式化表 |
示例：
# Web search — default settings
searchmcp web "open source privacy tools"
# News from the past week, JSON output
searchmcp news "AI regulation" --timelimit w --max-results 20 --json
# UK image search with strict safe-search
searchmcp images "data center" --region uk-en --safesearch strict
# Video search, second page of results
searchmcp videos "Tor browser tutorial" --page 2
# Book search with JSON output
searchmcp books "surveillance capitalism" --json
配置
高级用户的环境变量：
| 变量 | 默认值 | 描述 |
|---|---|---|
SEARCHMCP_USE_TOR |
true |
启用/禁用Tor(true/false) |
SEARCHMCP_TOR_PROXY |
socks5h://127.0.0.1:9050 |
Tor代理地址 |
SEARCHMCP_TOR_TIMEOUT |
30 |
请求超时（秒） |
例子：
# Use Tor Browser's proxy
SEARCHMCP_TOR_PROXY=socks5h://127.0.0.1:9150 searchmcp
# Increase timeout for slow connections
SEARCHMCP_TOR_TIMEOUT=60 searchmcp
MCP客户端配置
因为 searchmcp 作为控制台脚本安装在PATH中
每个MCP客户端的配置都是一样的——不需要路径硬编码。
{
"mcpServers": {
"searchmcp": {
"command": "searchmcp"
}
}
}
看 LLM安装助理 以下部分针对特定客户 说明（克劳德桌面、克劳德代码、光标、VS代码、LM Studio等）。
全面的隐私设置
SearchMCP保护您的搜索，但为了全面保护隐私，请考虑您的 整个数字足迹：
网页浏览器
| 浏览器 | 隐私级别 | 注意事项 |
|---|---|---|
| Tor 浏览器 | 最高 | 通过Tor路由所有流量 |
| Librewolf | 非常高 | 强化Firefox分叉 |
| 勇敢 | 高 | 内置Tor模式，广告拦截 |
| 火狐 | 中高 | 需要手动硬化 |
Firefox隐私扩展：
- uBlock Origin（广告/跟踪器阻止）
- 隐私徽章（跟踪学习）
- HTTPS无处不在（强制加密）
- NoScript（JavaScript控件）
- 容器标签（隔离站点）
电子邮件
| 服务 | 隐私级别 | 注意事项 |
|---|---|---|
| 原型邮件 | 非常高 | 端到端加密，瑞士管辖 |
| 图塔纳塔 | 非常高 | 端到端加密，德国管辖 |
| 邮箱.org | 高 | 以隐私为重点，德国管辖 |
| 自托管 | 最高 | 完全控制，需要专业知识 |
避免： Gmail、Outlook、Yahoo（扫描电子邮件并获利）
消息传递
| 应用程序 | 隐私级别 | 注意事项 |
|---|---|---|
| 信号 | 非常高 | 安全消息传递的黄金标准 |
| 会话 | 非常高 | 无需电话号码，分散 |
| 矩阵/元素 | 高 | 去中心化、自托管 |
| 荆棘 | 非常高 | 点对点，无需互联网即可工作 |
避免： WhatsApp（Meta）、Telegram（默认未加密）、短信
域名系统
您的DNS查询会显示您访问的每个网站。使用加密DNS：
| 服务 | 隐私级别 | 注意事项 |
|---|---|---|
| Quad9 | 非常高 | 阻止恶意软件，注重隐私 |
| Mullvad DNS | 非常高 | 没有记录，来自VPN提供商 |
| 下一个DNS | 高 | 可定制，一些日志记录 |
| Cloudflare（1.1.1.1） | 中等 | 速度很快，但Cloudflare可以看到查询 |
操作系统
| 操作系统 | 隐私级别 | 注意事项 |
|---|---|---|
| 尾巴 | 最高 | 实时操作系统，通过Tor路由所有流量 |
| Whonix | 非常高 | 基于VM的Tor路由 |
| Qubes 操作系统 | 非常高 | 通过分区实现安全 |
| Linux | 高 | 避免Ubuntu（遥测），使用Fedora/Debian |
避免： Windows（广泛遥测），macOS（一些遥测）
搜索引擎
| 引擎 | 隐私级别 | 注意事项 |
|---|---|---|
| 鸭鸭搜 | 高 | 无跟踪，由SearchMCP使用 |
| 起始页 | 高 | 谷歌搜索结果没有跟踪 |
| 西尔克斯 | 非常高 | 自助式元搜索 |
| 勇敢搜索 | 高 | 独立指数 |
避免： 谷歌、必应、雅虎（追踪一切）
发展
使用MCP检查器进行热重新加载
FastMCP v3提供了一个具有热重载和交互式检查器的开发服务器：
uv run fastmcp dev server.py
这将打开一个基于浏览器的MCP检查器，您可以在其中：
- 交互式测试工具
- 查看工具架构
- 调试请求/响应有效载荷
运行测试
# Run all tests
uv run pytest tests/ -v
# Run with coverage
uv run pytest tests/ -v --cov=searchmcp --cov-report=term-missing
# Run only unit tests (skip integration tests requiring Tor)
uv run pytest tests/ -v -m "not integration"
代码质量
# Type checking
uv run pyright src/
# Linting
uv run ruff check src/ tests/
# Format code
uv run ruff format src/ tests/
故障排除
“无法连接到Tor代理”
原因： Tor服务未运行。
解决方案：
# macOS
tor # or: brew services start tor
# Linux
sudo systemctl start tor
# Check if Tor is running
curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip
“Tor验证失败”
原因： Tor正在运行，但未正确路由流量。
解决方案：
- 重新启动Tor：
sudo systemctl restart tor - 检查Tor日志：
journalctl -u tor - 验证防火墙是否允许Tor连接
搜索速度慢
原因： 正常。Tor增加了隐私延迟。
解决：
- 增加超时时间：
SEARCHMCP_TOR_TIMEOUT=60 searchmcp - Tor通常比直接连接慢2-5倍
- 将此视为隐私的代价
速率限制
原因： DuckDuckGo速率限制Tor退出节点。
解决：
- 请等待几分钟，然后重试
- 重新启动Tor以获取新的退出节点：
sudo systemctl restart tor - 增加重试超时时间
安全最佳实践
- 始终使用VPN+Tor 为了最大限度的隐私
- 不要以root/admin身份运行 -SearchMCP将警告您
- 不要用
--with-logging生产中 -记录您的查询 - 保持Tor更新 -
brew upgrade tor或apt upgrade tor - 使用隐私浏览器 用于以下搜索结果链接
- 划分 -不要将匿名和已识别的活动混为一谈
API 参考
MCP工具
SearchMCP公开了五个MCP工具。所有工具都接受相同的参数集。
通用参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
query |
str |
（必填） | 搜索查询 |
max_results |
int |
10 |
结果数量（1-100） |
region |
str |
"wt-wt" |
地区代码(wt-wt =全球） |
safe_search |
str |
"moderate" |
安全过滤器： off, moderate，或 strict |
timelimit |
str | None |
None |
时间窗口： d, w, m，或 y |
backend |
str |
"auto" |
后端引擎： auto, all，或名称 |
page |
int |
1 |
结果页（1-100） |
web_search
web_search(
query: str,
max_results: int = 10,
region: str = "wt-wt",
safe_search: Literal["off", "moderate", "strict"] = "moderate",
timelimit: Literal["d", "w", "m", "y"] | None = None,
backend: str = "auto",
page: int = 1,
) -> list[dict]
# Returns: title, href, body
image_search
image_search(
query: str,
max_results: int = 10,
region: str = "wt-wt",
safe_search: Literal["off", "moderate", "strict"] = "moderate",
timelimit: Literal["d", "w", "m", "y"] | None = None,
backend: str = "auto",
page: int = 1,
) -> list[dict]
# Returns: title, image, thumbnail, url, height, width, source
news_search
news_search(
query: str,
max_results: int = 10,
region: str = "wt-wt",
safe_search: Literal["off", "moderate", "strict"] = "moderate",
timelimit: Literal["d", "w", "m", "y"] | None = None,
backend: str = "auto",
page: int = 1,
) -> list[dict]
# Returns: title, url, body, date, image, source
videos_search
videos_search(
query: str,
max_results: int = 10,
region: str = "wt-wt",
safe_search: Literal["off", "moderate", "strict"] = "moderate",
timelimit: Literal["d", "w", "m", "y"] | None = None,
backend: str = "auto",
page: int = 1,
) -> list[dict]
# Returns: title, content, description, duration, embed_html, embed_url,
# image_token, images, provider, published, publisher, statistics, uploader
books_search
books_search(
query: str,
max_results: int = 10,
region: str = "wt-wt",
safe_search: Literal["off", "moderate", "strict"] = "moderate",
timelimit: Literal["d", "w", "m", "y"] | None = None,
backend: str = "auto",
page: int = 1,
) -> list[dict]
# Returns: title, author, publisher, info, url, thumbnail
Python库API
SearchMCP也可以用作Python库。所有五个功能都接受
查询字符串和可选 SearchParams 对象。
from searchmcp.server import (
do_web_search,
do_image_search,
do_news_search,
do_videos_search,
do_books_search,
)
from searchmcp.params import SearchParams
params = SearchParams(
max_results=20,
region="us-en",
safesearch="moderate",
timelimit="w", # past week
backend="auto",
page=1,
)
results = do_web_search("open source privacy tools", params)
for r in results:
print(r["title"], r["href"])
# All functions share the same signature:
# do_web_search(query: str, params: SearchParams | None = None) -> list[dict]
# do_image_search(query: str, params: SearchParams | None = None) -> list[dict]
# do_news_search(query: str, params: SearchParams | None = None) -> list[dict]
# do_videos_search(query: str, params: SearchParams | None = None) -> list[dict]
# do_books_search(query: str, params: SearchParams | None = None) -> list[dict]
SearchParams 领域：
| 字段 | 类型 | 默认值 | 约束 |
|---|---|---|---|
max_results |
int |
10 |
1-100 |
region |
str |
"wt-wt" |
DuckDuckGo地区代码 |
safesearch |
str |
"moderate" |
off, moderate，或 strict |
timelimit |
str | None |
None |
d, w, m，或 y |
backend |
str |
"auto" |
auto, all，或发动机名称 |
page |
int |
1 |
1-100 |
LLM安装助理
可以向任何LLM（Claude、ChatGPT等）提供以下提示，以帮助您安装和配置SearchMCP：
Click to expand installation prompt
You are helping a user install SearchMCP, a privacy-first web search MCP server that routes all searches through Tor.
## Your Task
Guide the user through installing SearchMCP step by step. Ask questions to understand their setup, then provide specific commands and configuration.
## Step 1: Gather Information
Ask the user these questions (you can ask multiple at once):
1. **Operating System**: Are you using macOS, Linux (which distro?), or Windows?
2. **MCP Client**: Which MCP client do you use?
- Claude Desktop
- Claude Code (CLI)
- VS Code with Cline extension
- VS Code with Continue extension
- Cursor
- LM Studio
- AnythingLLM
- Qwen Code
- Other (ask which one)
3. **uv**: Do you have uv installed? (Check with `uv --version`)
4. **Tor**: Do you have Tor installed? (Check with `tor --version`)
## Step 2: Install Prerequisites
Based on their OS, provide the appropriate commands:
### uv
**macOS / Linux:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows（PowerShell）：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Tor
macOS：
brew install tor
brew services start tor # Run in background
Linux（Debian/Ubuntu）：
sudo apt update && sudo apt install tor
sudo systemctl start tor
sudo systemctl enable tor
Linux（Fedora/RHEL）：
sudo dnf install tor
sudo systemctl start tor
sudo systemctl enable tor
窗户： 下载Tor专家包https://www.torproject.org/download/tor/ 解压缩并运行tor.exe
步骤3：安装SearchMCP
# Clone the repository
git clone https://github.com/cspenn/searchmcp.git
cd searchmcp
# Install as a tool -- adds `searchmcp` to your PATH
uv tool install .
验证安装是否正常：
searchmcp --help
步骤4：配置MCP客户端
因为 searchmcp 在用户的PATH上，配置简单，在所有客户端上都是相同的：
{
"mcpServers": {
"searchmcp": {
"command": "searchmcp"
}
}
}
根据他们的MCP客户端，向他们展示放置位置：
克劳德桌面版
配置文件位置：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%APPDATA%\Claude\claude_desktop_config.json - Linux：
~/.config/Claude/claude_desktop_config.json
配置：
{
"mcpServers": {
"searchmcp": {
"command": "searchmcp"
}
}
}
如果他们已经配置了其他MCP服务器，请帮助他们合并配置。
克劳德代码（CLI）
选项1:CLI命令（推荐）：
claude mcp add --transport stdio --scope user searchmcp -- searchmcp
选项2：直接编辑配置文件：
配置文件： ~/.claude.json
{
"mcpServers": {
"searchmcp": {
"command": "searchmcp"
}
}
}
验证安装： 使用 /mcp Claude Code中的命令，用于检查服务器状态。
范围：
--scope user：适用于所有项目（推荐）--scope local：仅在当前项目中--scope project：通过共享.mcp.json文件
VS代码与Cline
配置位置： VS代码设置>临床>MCP服务器
或添加到 .vscode/mcp.json 在他们的工作空间中：
{
"mcpServers": {
"searchmcp": {
"command": "searchmcp"
}
}
}
VS代码并继续
配置位置： ~/.continue/config.json
添加到实验MCP服务器部分：
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "searchmcp"
}
}
]
}
}
光标
配置位置： 光标设置>MCP
{
"mcpServers": {
"searchmcp": {
"command": "searchmcp"
}
}
}
LM 工作室
配置文件位置：
- macOS/Linux：
~/.lmstudio/mcp.json - 窗户：
%USERPROFILE%\.lmstudio\mcp.json
要编辑： 打开LM Studio>程序选项卡（右侧边栏）>安装>编辑mcp.json
配置：
{
"mcpServers": {
"searchmcp": {
"command": "searchmcp"
}
}
}
保存mcp.json时，LM Studio会自动重新加载。确保 uv tool bin目录位于您的系统PATH中（uv在安装过程中打印此文件）。
万物皆可LLM
配置文件位置：
- macOS：
~/Library/Application Support/anythingllm-desktop/storage/plugins/anythingllm_mcp_servers.json - Linux：
~/.config/anythingllm-desktop/storage/plugins/anythingllm_mcp_servers.json - 窗户：
%APPDATA%\anythingllm-desktop\storage\plugins\anythingllm_mcp_servers.json
当您首次访问UI中的“代理技能”页面时，该文件会自动创建。
配置：
{
"mcpServers": {
"searchmcp": {
"command": "searchmcp"
}
}
}
重要提示： 在AnythingLLM中，您必须在提示前加上 @agent 使用MCP工具。例子： @agent search for privacy tools
您可以通过“代理技能”页面管理MCP服务器，而无需重新启动应用程序。
Qwen代码
选项1:CLI命令：
qwen mcp add searchmcp searchmcp
选项2：直接编辑配置文件：
配置文件位置：
- 用户配置：
~/.qwen/settings.json - 项目配置：
.qwen/settings.json
配置：
{
"mcpServers": {
"searchmcp": {
"command": "searchmcp"
}
}
}
管理服务器：
- 列出服务器：
qwen mcp list - 删除服务器：
qwen mcp remove searchmcp
通用MCP客户端
对于其他客户端，配置MCP服务器：
- 命令：
searchmcp - 运输： 标准
步骤5：验证安装
-
重新启动MCP客户端 （完全退出并重新打开）
-
检查Tor是否正在运行：
# Should return a JSON with Tor exit IP
curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip
- 测试搜索工具 通过要求MCP客户端搜索某些内容
故障排除
“无法连接到Tor代理”
Tor服务未运行。启动它：
- macOS：
brew services start tor - Linux：
sudo systemctl start tor - Windows：运行tor.exe
“找不到命令：searchmcp”
uv工具箱目录不在PATH中。运行：
uv tool update-shell
然后重新启动终端。
MCP服务器未出现
- 验证JSON是否有效（没有尾随逗号，引号正确）
- 完全重新启动MCP客户端
- 跑
searchmcp --help在终端中确认命令有效
搜索速度慢
正常-Tor增加了隐私延迟。搜索可能比直接连接长2-5秒。
LM Studio：MCP服务器未加载
- 检查mcp.JSON中的JSON语法（使用应用内编辑器）
- 确保
searchmcp在您的系统PATH中 - 尝试完全重新启动LM Studio
LLM：工具不起作用
- 确保在提示前加上前缀
@agent - 检查“代理技能”页面以验证服务器是否已启动
- 在“代理技能”页面上单击“刷新”以重新加载服务器
克劳德代码：服务器未连接
- 跑
/mcp检查服务器状态 - 删除并重新添加：
claude mcp remove searchmcp然后重新添加 - 检查
searchmcp --help在终端中工作
Qwen代码：服务器未加载
- 跑
qwen mcp list验证服务器是否已配置 - 检查settings.JSON中的JSON语法
- 确保
searchmcp在你的路径中
隐私验证
工作后，用户应在MCP客户端的日志或服务器输出中看到以下内容：
SEARCHMCP - Privacy Mode ENABLED
[✓] Tor proxy: socks5h://127.0.0.1:9050
[✓] Tor verified: exit IP xxx.xxx.xxx.xxx
[✓] Query logging: DISABLED
如果他们看到“隐私模式已禁用”，则Tor配置不正确。
</details>
## License
Apache 2.0 License - See LICENSE file for details.
## Contributing
Contributions welcome! Please ensure all changes maintain privacy-by-default
behavior and include tests.
## Disclaimer
SearchMCP provides privacy through Tor routing, but no system is perfect.
For activities requiring the highest level of anonymity, consider using Tails OS
and additional operational security measures. This tool is for legitimate
privacy protection, not for illegal activities.
