free_web_mcp

Free Web MCP – ein kostenloser MCP-Server, der Claude / Cursor / anderen MCP-Clients Websuche (DuckDuckGo, ohne API-Key) sowie Tools zum Web-Scraping und zur Textextraktion bereitstellt.

Detaillierte Anforderungen finden Sie in docs/free_web_mcp.md.

Tools

Related MCP server: qsearch

Schnellstart

uv sync

stdio-Modus (lokale Clients)

uv run free-web-mcp                # 或: uv run python -m free_web_mcp

Konfigurationsbeispiel für Cursor / Claude Desktop:

{
  "mcpServers": {
    "free-web-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/free_web_mcp", "free-web-mcp"]
    }
  }
}

HTTP-Modus (Remote-Bereitstellung)

uv run free-web-mcp --transport http   # 监听 .env 中的 HOST/PORT，默认 0.0.0.0:8000
curl http://localhost:8000/health      # -> {"status":"ok","service":"free-web-mcp"}

MCP-streamable-http-Endpunkt: http://<host>:8000/mcp.

Docker

# 默认：仅 HTTP 抓取路径
docker build -f docker/Dockerfile -t free-web-mcp .
docker run --rm -p 8000:8000 free-web-mcp

# 启用 headless 渲染（构建时下载 Chromium ~150MB；首次启动约 1-3s）
docker build -f docker/Dockerfile --build-arg INSTALL_PLAYWRIGHT_BROWSERS=true -t free-web-mcp:render .
docker run --rm -p 8000:8000 -e RENDER_ENABLED=true free-web-mcp:render

Konfiguration (.env)

.env.example nach .env kopieren und nach Bedarf anpassen; .env wird nicht ins Repository aufgenommen.

Entwicklung

uv run pytest                  # 测试
uv run ruff check .            # lint
uv run mypy                    # 类型检查（strict）

Architektur

Strikte Schichtung: MCP-Tool-Ebene → Service-Ebene (SearchService/FetchService) → Provider/HTTP-Ebene. Die Suchquelle ist austauschbar (aktuelle Implementierung: DuckDuckGoProvider); HTTP läuft einheitlich über WebClient. Für die Textextraktion wird bevorzugt trafilatura verwendet, mit BeautifulSoup als Fallback. Details siehe AGENTS.md.