free_web_mcp

Free Web MCP —— un servidor MCP gratuito que proporciona herramientas de búsqueda web (DuckDuckGo, sin necesidad de API Key) y extracción de contenido web + extracción de texto para Claude / Cursor / otros clientes MCP.

Consulte los requisitos detallados en docs/free_web_mcp.md.

Herramientas

Related MCP server: qsearch

Inicio rápido

uv sync

Modo stdio (cliente local)

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

Ejemplo de configuración para Cursor / Claude Desktop:

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

Modo HTTP (despliegue remoto)

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"}

Endpoint MCP streamable-http: 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

Configuración (.env)

Copie .env.example a .env y modifíquelo según sea necesario; .env no se incluye en el repositorio.

Desarrollo

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

Arquitectura

Estratificación estricta: capa de herramientas MCP → capa de servicios (SearchService/FetchService) → capa de proveedor/HTTP. La fuente de búsqueda es conectable (implementación actual: DuckDuckGoProvider), HTTP usa uniformemente WebClient, la extracción de contenido prioriza trafilatura y usa BeautifulSoup como respaldo. Consulte AGENTS.md para más detalles.