web-search-mcp
This server provides web search and page-fetching tools for Claude Code, working without any API key by default.
web_search(query, count=5, lang="auto"): search the web and return title/url/snippet results; auto-detects Vietnamese queries, supports explicit
vi/enlanguage preference.fetch_page(url, max_chars=20000): retrieve a web page's content as markdown, with fallback from Jina Reader to DDGS extraction.
search_stats(hours=24): view provider success rates, latency, and recent errors to decide whether to add API keys.
Runs without an API key: uses a free
ddgsbackend chain (Serper/Tavily only if their API keys are set), so you can search immediately.Configurable via environment variables: cache TTL, max results per domain, retries, provider backends, stats retention, and more.
Also usable as a CLI: run
web-search-mcp search,fetch,stats, ordoctordirectly from the terminal without an MCP client.Caching and metrics: search/fetch results are cached with TTL, and usage metrics are stored in SQLite for later analysis.
Multiple install options: run via
uvx/npx, add it to Claude Code withclaude mcp add, and set API keys if you want faster or more reliable providers.
Allows Brave to be used as a search engine backend in the free search provider chain, returning web results with titles, URLs, and snippets.
Allows DuckDuckGo to be used as a search engine backend in the free search provider chain, returning web results with titles, URLs, and snippets.
Allows Google to be used as a search engine backend, both through the free ddgs-based provider and via Serper.dev when an API key is configured.
Allows Mojeek to be used as a search engine backend in the free search provider chain.
Allows Startpage to be used as a search engine backend in the free search provider chain.
Allows Wikipedia to be used as a search source in the free provider chain, providing reliable search results with minimal rate limiting.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@web-search-mcp search for latest AI news and summarize top 3 results"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
web-search-mcp
MCP server cung cấp web search cho Claude Code CLI. Chạy được không cần API key nào.
uvx web-search-mcp-free # hoặc: npx -y @quangnx99/web-search-mcpTools
Tool | Mô tả |
| Tìm kiếm web, trả về title/url/snippet |
| Lấy nội dung trang dưới dạng markdown |
| Xem thống kê provider: tỷ lệ thành công, latency, lỗi gần nhất |
lang="auto" phát hiện tiếng Việt theo dấu trong truy vấn rồi chuyển sang vi
(dùng region vn-vi). Truy vấn không dấu như "Docker Vietnam" sẽ bị coi là
en — đặt lang="vi" tường minh nếu cần.
Related MCP server: openai-search-mcp
Provider chain
Server thử lần lượt cho tới khi có kết quả:
Serper.dev — Google SERP, nhanh nhất (~0.5s). Chỉ dùng nếu có
SERPER_API_KEY.Tavily — search tối ưu cho LLM. Chỉ dùng nếu có
TAVILY_API_KEY.free— quaddgs, không cần key. Đây là mặc định.
fetch_page: thử Jina Reader trước, hỏng thì chuyển sang ddgs.extract().
Về tầng free — những gì đã đo được
Mặc định là FREE_BACKENDS=auto, và đây là lựa chọn có cơ sở:
Cấu hình | Thành công (5 query) | Latency TB |
| 5/5 | 4.2s |
danh sách thủ công 6 engine | 0/5 | 3.0s |
auto thắng vì nó đẩy wikipedia + grokipedia lên đầu — hai nguồn gần như
không bao giờ bị rate limit, nên luôn có ít nhất một kết quả.
Ba điều phản trực giác về ddgs, đều đã kiểm chứng:
Liệt kê nhiều engine KHÔNG tăng khả năng chống rate limit.
ddgsgiới hạn số engine chạy song song bằngmin(số_provider, ceil(max_results/10) + 1). Vớicount=5mặc định thì chỉ 2 engine được dùng, bất kể bạn khai bao nhiêu.Một engine timeout làm hỏng cả request (
wait(..., FIRST_EXCEPTION)). Vì vậy server retry mặc định 2 lần — engine đượcddgsshuffle mỗi lượt nên lần thử lại thường bốc được tổ hợp khác.bingkhông phải backend hợp lệ. Danh sách thật:brave,duckduckgo,google,grokipedia,mojeek,startpage,wikipedia,yahoo,yandex.bingchỉ là provider nằm dướiduckduckgo/yahoo. Khai tên sai thìddgsâm thầm rơi vềauto— server sẽ cảnh báo ra stderr thay vì để bạn tưởng cấu hình đang có hiệu lực.
Đánh giá thật: tầng free dùng tốt cho tra cứu thường ngày, nhưng latency
3–9s và độ ổn định dao động. Nếu search nhiều, SERPER_API_KEY (2.500 query
miễn phí, không cần thẻ) là nâng cấp đáng giá.
Biến môi trường
Tất cả đều tuỳ chọn.
Biến | Mặc định | Ghi chú |
|
| Danh sách engine, phân tách bởi dấu phẩy. Tên sai bị lọc kèm cảnh báo |
|
| Số lần thử lại tầng free |
| — | https://serper.dev — 2.500 query miễn phí |
| — | https://tavily.com — 1.000 credit/tháng |
| — | Tăng rate limit |
|
| TTL cache search (giây) |
|
| TTL cache fetch (giây) |
|
| Số URL tối đa giữ lại cho mỗi domain |
| thư mục cache của OS | Đường dẫn file |
|
| Số entry cache tối đa giữ trước khi trim |
|
| Số bản ghi metrics tối đa (SQLite) |
Cache mặc định nằm trong thư mục cache theo chuẩn OS (
platformdirs.user_cache_dir("web-search-mcp")), không phải cạnh source — quan trọng khi cài quauvx/npx, vì môi trường đó bị xoá sau mỗi lần chạy.
Cài đặt
Cần uv (đi kèm uvx).
uv tự lo Python >= 3.12, không cần cài trước.
uvx web-search-mcp-free # chạy MCP server trên stdio
claude mcp add --scope user web-search -- uvx web-search-mcp-free
claude mcp list # kỳ vọng: web-search ... ✔ ConnectedHoặc qua npm, nếu bạn quen npx (cần Node >= 18):
npx -y @quangnx99/web-search-mcp
claude mcp add --scope user web-search -- npx -y @quangnx99/web-search-mcpGói npm là shim: nó gọi uvx (hoặc python -m web_search_mcp nếu bạn đã
pip install web-search-mcp-free) rồi chuyển tiếp stdio nguyên vẹn. Khi máy
chưa có gì chạy được, shim dừng kèm hướng dẫn cài — nó không tự tải và chạy
script lạ.
Thêm API key sau khi đã cài:
claude mcp remove --scope user web-search
claude mcp add --scope user --env SERPER_API_KEY=<key> \
web-search -- uvx web-search-mcp-freeTrên Windows không cần bọc cmd /c: uv/uvx là .exe thật.
Tên gọi: distribution trên PyPI là
web-search-mcp-free— tênweb-search-mcpvàwebsearch-mcp-serverđều đã có dự án khác chiếm (PyPI chặn cả tên chỉ tương tự, không chỉ tên trùng hệt). Package npm là@quangnx99/web-search-mcp, còn lệnh chạy trong mọi trường hợp đều làweb-search-mcp. Package cũng cung cấp thêm aliasweb-search-mcp-freevìuvx <tên-gói>chỉ chạy được khi executable trùng tên gói.
Lỗi thường gặp
An executable named 'web-search-mcp-free' is not provided by package ...
→ bạn đang chạy bản PyPI 0.1.0, bản này chưa có alias trùng tên gói. Lấy bản mới:
uvx --refresh web-search-mcp-freeHoặc dùng dạng --from, chạy được với mọi bản đã phát hành:
uvx --from web-search-mcp-free web-search-mcpCLI dùng tay
Server cũng là một CLI bình thường — tiện thử nhanh mà không cần MCP client:
web-search-mcp search "giá vàng hôm nay" --count 3
web-search-mcp fetch https://example.com --max-chars 4000
web-search-mcp stats --hours 48
web-search-mcp doctor # in đường dẫn cache + biến môi trường đã đặt
web-search-mcp serve # MCP server trên stdio (mặc định khi không tham số)search/fetch trả exit code 1 khi thất bại nên dùng được trong script. Lệnh
con gọi thẳng hàm mà MCP tool dùng — cache, retry, fallback và metrics đi qua
đúng một đường code.
Chạy từ source
uv sync
uv run web-search-mcp doctorTest
uv sync # cài pytest ở dependency-group dev
uv run pytest -q # 99 test, không gọi mạng
cd npm && npm test # 5 test cho shim npm (node --test)Toàn bộ test mock lớp mạng nên chạy offline và deterministic. Trọng tâm phủ:
_valid_backendslọc tên sai (bing) và rơi vềautokhi không còn gì hợp lệretry của
free_search, kể cả khi engine timeout_is_binarychặn PDF/ZIP/ảnh màddgs.extract()trả về dạng byte thô — gồm test hồi quy đảm bảo văn bản tiếng Việt không bị nhận nhầm là nhị phânthứ tự fallback của
fetch_page, và không cache nội dung lỗicache: TTL, hết hạn, tách entry theo
lang/count, normalize key (lowercase + strip)metrics: ghi/đọc, giới hạn dung lượng, windowing theo thời gian
locale: map
lang→(region, gl, hl)cho DDGS/Serper/Tavilydedupe domain: giữ tối đa 2 URL/domain, ưu tiên đa dạng
Giới hạn đã biết
cache.dbchỉ trim bản ghi cũ khi vượt ngưỡng, không có vacuum định kỳ.
Available Tools
3 toolsfetch_pageA
Lấy nội dung đầy đủ của một trang web dưới dạng markdown.
Inputs: url (required), max_chars. Returns: result
search_statsA
Xem provider nào hay lỗi và chậm bao nhiêu, trong N giờ gần nhất.
Dùng khi search trả kết quả kém hoặc chậm, để biết nên đặt API key hay không.
Inputs: hours. Returns: result
web_searchB
Tìm kiếm trên web và trả về danh sách kết quả.
Inputs: query (required), lang, count. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: web_search returns result lists, fetch_page retrieves full page content, and search_stats monitors provider performance. There is no meaningful overlap between them.
All tool names follow a consistent verb_noun snake_case pattern: web_search, fetch_page, and search_stats. The naming is predictable and easy for an agent to parse.
Three tools is well-scoped for a web search server: search, fetch, and operational diagnostics. Each tool earns its place with no redundancy.
The core workflow of searching the web and then fetching full page content is fully covered, and search_stats adds useful operational insight. There are no obvious dead ends or missing critical operations for this domain.
Maintenance
Related MCP Connectors
Free web search for AI agents. No API key required. Hosted MCP in active development.
Web search API and MCP server for developers building AI agents.
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
Docs: https://docs.keenable.ai/mcp-server Keenable is a free, remote MCP server that gives agents access to the web index. Search the web with ranked results and date/site filters, then fetch any indexed page as clean markdown. Works out of the box with no account or API key.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables web search through Exa or Parallel APIs for MCP-compatible AI clients like Cursor and Claude Code.1MIT
- AlicenseAqualityDmaintenanceEnables Claude to perform real-time web searches and fetch web page content via MCP, using OpenAI-compatible APIs with optional Tavily or Firecrawl engines.521 npm13MIT
- AlicenseAqualityDmaintenanceEnables AI agents to perform multi-engine web search, fetch web pages, and extract clean Markdown content via MCP, with no API keys required.377 PyPI11MIT
- AlicenseNot gradedqualityBmaintenanceEnables web search and scraping through MCP, running locally with courtesy rate limiting and caching.MIT