Open WebSearch

Open-WebSearch

🇨🇳 中文 | 🇺🇸 English

open-websearch provides an MCP server, CLI, and local daemon, and can also be paired with skill-guided agent workflows for live web search and content retrieval without API keys.

Features

• Web search using multi-engine results
  • bing
  • baidu
  • linux.do temporarily unsupported
  • csdn
  • duckduckgo
  • exa
  • brave
  • juejin
  • startpage
  • sogou
• HTTP proxy configuration support for accessing restricted resources
• No API keys or authentication required
• Returns structured results with titles, URLs, and descriptions
• Configurable number of results per search
• Customizable default search engine
• Support for fetching individual article content
  • csdn
  • github (README files)
  • generic HTTP(S) page / Markdown content

Choose the Right Path

• MCP
  • Best when you want to connect open-websearch to Claude Desktop, Cherry Studio, Cursor, or another MCP client.
• CLI
  • Best for one-shot local commands, shell scripts, and direct terminal usage.
• Local daemon
  • Best when you want a reusable long-lived local HTTP service exposing status, GET /health, and POST /search / POST /fetch-*. Start it explicitly with open-websearch serve and check it with open-websearch status.
• Skill
  • Best as an agent-facing guidance layer for setup and usage. A skill does not replace MCP, CLI, or the local daemon; it typically works together with the CLI and/or local daemon to help an agent discover, activate, and use the smallest working path.

Use with a Skill

Install the open-websearch skill for your agent first:

npx skills add https://github.com/Aas-ee/open-webSearch --skill open-websearch

On first use, the skill typically follows this path: detect whether a usable open-websearch path already exists, guide setup/enablement if it does not, validate that the capability is active, and only then continue with search or fetch through the smallest working path.

If the current environment cannot complete setup or activation automatically, you can explicitly have the agent start the local daemon first:

open-websearch serve
open-websearch status

Keep installation proxy settings separate from runtime proxy settings:

• Installation proxy / mirror
  • Use this when the skill or agent is installing open-websearch, playwright, or other npm packages.
  • In restricted networks, npm-specific flags or npm config often work better than generic shell proxy variables, for example:

npm --proxy http://127.0.0.1:7890 --https-proxy http://127.0.0.1:7890 install -g open-websearch

• Runtime proxy
  • Use this when the daemon is already installed and is about to perform live search / fetch work.
  • This affects the open-websearch network traffic after serve starts, for example:

USE_PROXY=true PROXY_URL=http://127.0.0.1:7890 open-websearch serve

If the agent can only get through the package-install step with npm proxy settings, but live search/fetch also needs a proxy after startup, those are two separate configuration steps and should be handled separately.

CLI and Local Daemon

CLI is for one-shot execution. The local daemon is a long-lived local HTTP service for repeated calls with lower startup friction. Use open-websearch serve as the explicit daemon start command and open-websearch status as the explicit daemon status command.

Action commands such as search and fetch-web try the default local daemon first when it is available. If you pass --daemon-url, that daemon path becomes explicit and silent fallback to direct execution is disabled.

Build first:

npm run build

Start the local daemon:

npm run serve
# globally installed: open-websearch serve

Check status:

npm run status -- --json
# globally installed: open-websearch status --json

Run a one-shot local CLI search:

npm run search:cli -- "open web search" --json

Notes:

• Bare open-websearch is the MCP server compatibility entrypoint, not the recommended daemon start command for agent automation.
• For content extraction, prefer searching first and then fetching a more specific result page. Some homepages and JS-heavy landing pages may not expose readable article text through fetch-web.

For the local daemon HTTP API (serve, status, GET /health, POST /search, POST /fetch-*), see docs/http-api.md.

TODO

• Support for Bing (already supported), DuckDuckGo (already supported), Exa (already supported), Brave (already supported), Sogou (already supported), Google and other search engines
• Support for more blogs, forums, and social platforms
• Optimize article content extraction, add support for more sites
• Support for GitHub README fetching (already supported)

Installation Guide

If you are using open-websearch as an MCP server, continue with the MCP-oriented setup below.

NPX Quick Start (Recommended)

The fastest way to get started:

# Basic usage
npx open-websearch@latest

# With environment variables (Linux/macOS)
DEFAULT_SEARCH_ENGINE=duckduckgo ENABLE_CORS=true npx open-websearch@latest

# Windows PowerShell
$env:DEFAULT_SEARCH_ENGINE="duckduckgo"; $env:ENABLE_CORS="true"; npx open-websearch@latest

# Windows CMD
set MODE=stdio && set DEFAULT_SEARCH_ENGINE=duckduckgo && npx open-websearch@latest

# Cross-platform (requires cross-env, Used for local development)
npm install -g open-websearch
npx cross-env DEFAULT_SEARCH_ENGINE=duckduckgo ENABLE_CORS=true open-websearch

Environment Variables:

Common configurations:

# Enable proxy for restricted regions
USE_PROXY=true PROXY_URL=http://127.0.0.1:7890 npx open-websearch@latest

# Only if a target website has a broken certificate chain
FETCH_WEB_INSECURE_TLS=true npx open-websearch@latest

# Request first, then fallback to Playwright if available
SEARCH_MODE=auto npx open-websearch@latest

# Force request-only Bing search
SEARCH_MODE=request npx open-websearch@latest

# Full configuration
DEFAULT_SEARCH_ENGINE=duckduckgo ENABLE_CORS=true USE_PROXY=true PROXY_URL=http://127.0.0.1:7890 PORT=8080 npx open-websearch@latest

Browser-enhanced Bing fallback is opt-in. The published package does not bundle Playwright anymore. Enable it manually with one of these setups:

1. Full local Playwright install:

npm install playwright
npx playwright install chromium
SEARCH_MODE=auto npx open-websearch@latest

1. Reuse an existing browser binary with a slim client:

npm install playwright-core
PLAYWRIGHT_PACKAGE=playwright-core PLAYWRIGHT_EXECUTABLE_PATH=/path/to/chromium SEARCH_MODE=auto npx open-websearch@latest

1. Reuse a Playwright package that already exists elsewhere on the machine:

PLAYWRIGHT_MODULE_PATH=/absolute/path/to/node_modules/playwright SEARCH_MODE=playwright npx open-websearch@latest

1. Connect to an existing remote browser:

npm install playwright-core
PLAYWRIGHT_PACKAGE=playwright-core PLAYWRIGHT_WS_ENDPOINT=ws://127.0.0.1:3000/ SEARCH_MODE=auto npx open-websearch@latest

1. Reuse a local Chrome/Chromium session over CDP:

npm install playwright-core

# Start Chrome/Chromium with a debugging port first
chrome --remote-debugging-port=9222 --user-data-dir=/tmp/open-websearch-chrome

# Then connect through CDP
PLAYWRIGHT_PACKAGE=playwright-core PLAYWRIGHT_CDP_ENDPOINT=http://127.0.0.1:9222 SEARCH_MODE=auto npx open-websearch@latest

This is the most practical setup when you want to reuse your own logged-in or previously verified browser session.

Windows PowerShell example:

npm install playwright-core

& "$env:LOCALAPPDATA\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 `
  --user-data-dir="$env:TEMP\open-websearch-chrome"

$env:PLAYWRIGHT_PACKAGE="playwright-core"
$env:PLAYWRIGHT_

…