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.

Sponsor

Swiftproxy provides high-quality static residential proxies with stable IPs for multi-account management, automation, web scraping, and secure online operations. Protect your accounts with clean IPs and reliable proxy infrastructure. Static proxy traffic is valid for 30 days with unlimited usage. Get 10% off with code PROXY90.

Features

• Web search using multi-engine results
  • bing
  • baidu
  • linux.do temporarily unsupported
  • csdn
  • duckduckgo
  • exa
  • brave
  • juejin
  • startpage
  • sogou
  • hackernews
• 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), Hacker News (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: