AI导哈

隐私搜索服务器

一个基于SearXNG的隐私保护型网络搜索服务器，为Claude Desktop和Claude Code提供匿名搜索功能。

  • by Basti-Fantasti
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Basti-Fantasti/searXNG-mcp-server

使用说明

SearXNG MCP服务器

一种模型上下文协议（MCP）服务器，通过以下方式提供以隐私为中心的网络搜索功能 SearXNG，一个免费的元搜索引擎。此服务器使Claude Desktop和Claude Code能够在维护用户隐私的同时执行网络搜索。

特性

  • 以隐私为中心的搜索：利用SearXNG进行匿名、无跟踪器的网络搜索
  • 高级搜索参数：支持类别、语言过滤器和时间范围
  • MCP集成：与Claude Desktop和Claude Code无缝集成
  • 异步架构：内置async/await，实现无阻塞、高效的操作
  • 类型安全：用于稳健数据验证的完整类型提示和Pydantic模型
  • 可配置的：基于环境的配置，实现灵活部署
  • 本地SearXNG实例：使用Docker在本地运行SearXNG以实现完全的隐私控制

先决条件

安装前，请确保：

  • Python 3.13+ - 下载Python
  • 紫外线 -快速Python包安装程序和解析器
    # Install uv (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install uv (Windows)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  • 码头工人 -需要在本地运行SearXNG

安装

1.克隆存储库

git clone https://github.com/Basti-Fantasti/searXNG-mcp-server.git
cd searxng-mcp-server

2.安装依赖项

# Install dependencies using uv
uv sync

# This will create a virtual environment and install all required packages

3.配置环境（可选）

创建一个 .env 要自定义配置的文件：

# .env
SEARXNG_BASE_URL=http://localhost:9999
SEARXNG_TIMEOUT=10
LOG_LEVEL=INFO
MAX_RESULTS_LIMIT=50

配置选项：

变量 描述 默认值
SEARXNG_BASE_URL SearXNG实例的基本URL http://localhost:8080
（使用 9999 使用docker编写）
SEARXNG_TIMEOUT 请求超时（秒） 10
LOG_LEVEL 记录详细程度（调试/信息/警告/错误/关键） INFO
MAX_RESULTS_LIMIT 每个查询允许的最大结果数 50

SearXNG Docker设置

服务器需要一个正在运行的SearXNG实例。使用Docker Compose进行简单设置：

1.启动SearXNG

# Start SearXNG container in detached mode
docker-compose up -d

这将：

  • 拉取SearXNG Docker官方镜像
  • 在端口9999上启动SearXNG（从集装箱端口8080映射）
  • 安装 searxng-settings.yml 配置文件

2.验证SearXNG是否正在运行

# Check container status
docker ps | grep searxng

# Test SearXNG API
curl "http://localhost:9999/search?q=test&format=json"

3.停止SearXNG

# Stop the container
docker-compose down

4.查看日志

# View SearXNG logs
docker logs searxng

# Follow logs in real-time
docker logs -f searxng

Claude代码配置

要将此MCP服务器与Claude Code一起使用，请将其添加到您的MCP配置中：

全局配置（所有项目）

编辑 ~/.claude/mcp.json:

{
  "mcpServers": {
    "searxng": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/searxng-mcp-server",
        "run",
        "searxng-mcp"
      ],
      "env": {
        "SEARXNG_BASE_URL": "http://localhost:9999"
      }
    }
  }
}

项目级配置

创建 .claude/mcp.json 在项目根目录中：

{
  "mcpServers": {
    "searxng": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/searxng-mcp-server",
        "run",
        "searxng-mcp"
      ],
      "env": {
        "SEARXNG_BASE_URL": "http://localhost:9999"
      }
    }
  }
}

Windows路径示例

{
  "mcpServers": {
    "searxng": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\absolute\\path\\to\\searxng-mcp-server",
        "run",
        "searxng-mcp"
      ],
      "env": {
        "SEARXNG_BASE_URL": "http://localhost:9999"
      }
    }
  }
}

重要提示：

  • 使用 绝对路径，而不是相对路径
  • 修改配置后重新启动Claude Code
  • 在使用搜索工具之前，确保SearXNG正在运行

Claude桌面配置

要将此MCP服务器与Claude Desktop一起使用，请将其添加到配置文件中：

macOS/Linux

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "searxng": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/searxng-mcp-server",
        "run",
        "searxng-mcp"
      ],
      "env": {
        "SEARXNG_BASE_URL": "http://localhost:9999"
      }
    }
  }
}

视窗

编辑 %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "searxng": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\absolute\\path\\to\\searxng-mcp-server",
        "run",
        "searxng-mcp"
      ],
      "env": {
        "SEARXNG_BASE_URL": "http://localhost:9999"
      }
    }
  }
}

重要提示：

  • 使用 绝对路径，而不是相对路径
  • 修改配置后重新启动Claude Desktop
  • 在启动Claude Desktop之前，确保SearXNG正在运行

使用示例

配置后，您可以使用 web_search 克劳德桌面或克劳德代码中的工具：

基本搜索

Search for "Python async programming tutorials"

搜索结果最多

Search for "machine learning news" and return up to 20 results

特定类别搜索

Search for "climate change" in the science and news categories

可用类别：

  • general -一般网络搜索
  • news -新闻文章
  • images -图片搜索
  • videos -视频内容
  • files -文件下载
  • science -科学论文和资源
  • map -地图和位置
  • music -音乐内容
  • it -IT和技术资源

特定语言搜索

Search for "recettes françaises" in French

使用ISO 639-1语言代码： en, de, fr, es, it, pt, ru, zh, ja等等。

时间范围筛选搜索

Search for "AI breakthroughs" from the past week

可用时间范围：

  • day -过去24小时
  • week -过去7天
  • month -过去30天
  • year -过去一年

组合高级搜索

Search for "renewable energy" in English, in science and news categories, from the past month, limit to 15 results

故障排除

SearXNG连接问题

问题： Failed to connect to SearXNG

解决：

  • 验证SearXNG是否正在运行： docker ps | grep searxng
  • 检查URL是否正确： curl http://localhost:9999/search?q=test&format=json
  • 确保端口（9999）与您的 docker-compose.yaml 和配置
  • 检查Docker是否正在运行： docker info

超时错误

问题： Search request timed out

解决：

  • 增加超时时间 .env: SEARXNG_TIMEOUT=30
  • 检查SearXNG性能： docker logs searxng
  • 重新启动SearXNG容器： docker-compose restart

Claude Desktop找不到服务器

问题： MCP服务器未显示在Claude Desktop中

解决：

  • 确认您正在使用 绝对路径 在配置中
  • 检查路径是否存在： ls /absolute/path/to/searxng-mcp-server
  • 完全重新启动克劳德桌面
  • 检查Claude Desktop日志是否有错误

Windows上的权限错误

问题： Permission denied 运行uv或访问文件时

解决：

  • 以管理员身份运行终端
  • 检查项目目录中的文件权限
  • 确保您的防病毒软件不会阻止uv或Python

未返回搜索结果

问题： 搜索返回空结果

解决：

  • 直接测试SearXNG： curl "http://localhost:9999/search?q=test&format=json"
  • 在中检查SearXNG设置 searxng-settings.yml
  • 验证搜索引擎是否在SearXNG中启用
  • 尝试其他查询或删除筛选器

开发设置

安装开发依赖项

# Install dev dependencies
uv sync --dev

这将安装其他工具：

  • pytest -测试框架
  • pytest-asyncio -异步测试支持
  • pytest-cov -覆盖率报告
  • mypy -静态类型检查器
  • ruff -快速Python linter和格式化程序

运行测试

# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov=src/searxng_mcp --cov-report=html

# Run specific test file
uv run pytest tests/test_server.py

# Run with verbose output
uv run pytest -v

# Run async tests
uv run pytest -v tests/test_searxng_client.py

覆盖率报告生成于 htmlcov/index.html.

代码质量检查

# Run linter
uv run ruff check .

# Auto-fix linting issues
uv run ruff check --fix .

# Format code
uv run ruff format .

# Type checking
uv run mypy src/searxng_mcp

在本地运行服务器

# Run the MCP server
uv run searxng-mcp

服务器使用stdio传输，并期望stdin上有MCP协议消息。

项目结构

searxng-mcp-server/
├── src/
│   └── searxng_mcp/
│       ├── __init__.py         # Package initialization
│       ├── __main__.py         # Entry point
│       ├── server.py           # MCP server implementation
│       ├── searxng_client.py   # SearXNG HTTP client
│       ├── config.py           # Configuration management
│       └── models.py           # Pydantic data models
├── tests/
│   ├── test_server.py          # Server tests
│   ├── test_searxng_client.py  # Client tests
│   └── test_config.py          # Config tests
├── docker-compose.yaml         # SearXNG container config
├── searxng-settings.yml        # SearXNG configuration
├── pyproject.toml              # Project metadata and dependencies
├── CLAUDE.md                   # Claude Code project guide
└── README.md                   # This file

贡献

欢迎投稿！以下是如何做出贡献：

1.分叉和克隆

git clone <YOUR_REPO_URL>.git
cd searxng-mcp-server

2.创建特征分支

git checkout -b feature/your-feature-name

3.做出改变

  • 遵循现有的代码风格（由Ruff强制执行）
  • 为新功能添加测试
  • 根据需要更新文档
  • 确保所有测试通过： uv run pytest
  • 运行linting： uv run ruff check .
  • 运行类型检查： uv run mypy src/searxng_mcp

4.提交你的更改

git add .
git commit -m "Add your descriptive commit message"

使用常规提交消息：

  • feat: -新功能
  • fix: -Bug修复
  • docs: -文档更改
  • test: -测试添加或更改
  • refactor: -代码重构
  • chore: -维护任务

5.推送和创建拉取请求

git push origin feature/your-feature-name

然后在GitHub上创建一个Pull Request：

  • 变更的清晰描述
  • 参考任何相关问题
  • 屏幕截图/示例（如适用）

代码审查流程

  • 所有PR都需要通过测试
  • 代码必须通过linting和类型检查
  • 至少需要一个维护人员批准
  • 必须更新文档以应对用户面临的更改

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

支持

以隐私为出发点。自由搜索。

相关 MCP