my-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
  • Domestic engines (no proxy needed): bing, baidu, csdn, juejin, sogou
  • Overseas engines (⚠️ proxy required in mainland China): duckduckgo, exa, brave, startpage
• 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 my-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 my-websearch serve and check it with my-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 my-websearch skill for your agent first:

npx skills add https://gitee.com/wtznicy/my-websearch --skill my-websearch

On first use, the skill typically follows this path: detect whether a usable my-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:

my-websearch serve
my-websearch status

Keep installation proxy settings separate from runtime proxy settings:

• Installation proxy / mirror
  • Use this when the skill or agent is installing my-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 my-websearch

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

USE_PROXY=true PROXY_URL=http://127.0.0.1:7890 my-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 my-websearch serve as the explicit daemon start command and my-websearch status as the explicit daemon status command.

Windows console note: CLI JSON output is UTF-8. On the legacy Windows console (GBK code page 936) Chinese characters may render as mojibake in cmd/other terminals (redirecting to a file is fine). Run chcp 65001 first, or use Windows Terminal.

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: my-websearch serve

Check status:

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

Run a one-shot local CLI search:

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

Notes:

• Bare my-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.
• --min-results N on search auto-runs additional engines (not already requested) until at least N results come back; defaults to off.
• Bing's HTTP mode is the most anti-bot-prone engine. If you hit verification pages often: (a) spread load with engines: ["duckduckgo", "brave"] on Bing-unrelated queries, or (b) set BING_PLAYWRIGHT_FALLBACK=false plus --min-results so a blocked Bing automatically cascades to lighter engines instead of launching a Playwright browser.
• cache-clear clears the in-memory search TTL cache — useful after an engine recovers from an outage or when a stale anti-bot page got cached:
  bash

  Copy

  my-websearch cache-clear
  

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

Installation Guide

If you are using my-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 my-websearch@latest

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

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

# Windows CMD
set MODE=stdio && set DEFAULT_SEARCH_ENGINE=bing && npx my-websearch@latest

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

Environment Variables: