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-mcpsearch 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.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Địa chỉ trang cần đọc. | |
| max_chars | No | Số ký tự tối đa trả về (cắt bớt nếu vượt quá). |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the output format (markdown) and the max_chars truncation behavior is in the schema. It doesn't mention potential issues like paywalls, dynamic content, or rate limits, but for a simple fetch tool the description is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, clear sentence in Vietnamese. It is front-loaded with the main action and output format. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with 2 parameters, 100% schema coverage, and an output schema. The description covers the core purpose and output format. It could mention edge cases like non-HTML content or errors, but for a straightforward fetch tool this is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds the output format (markdown) but doesn't add much beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Lấy' = fetch/retrieve) and resource ('nội dung đầy đủ của một trang web' = full content of a webpage) and the output format (markdown). It is clear what the tool does, though it doesn't explicitly distinguish itself from siblings like web_search or search_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this tool when you need the full content of a webpage as markdown. It doesn't explicitly state when not to use it or mention alternatives like web_search for searching or search_stats for statistics. The context is clear but exclusions/alternatives are not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| hours | No | Khoảng thời gian thống kê (giờ). |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It describes the tool's purpose (showing provider faults and slowness) but does not explicitly state whether it is read-only, side-effect-free, or requires any authentication. It also doesn't describe the output format, though an output schema exists. The behavioral transparency is moderate; it gives context but not explicit guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. The core purpose is stated first, followed by usage guidance. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter tool with an output schema, the description covers the purpose and usage. It could mention what metrics are shown, but the phrase 'provider nào hay lỗi và chậm bao nhiêu' already conveys that. It is sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the parameter ('hours') with a description and default. The description references 'N giờ' which aligns with the parameter. No additional semantics are needed; baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('xem' – view) and resource (provider performance), and clarifies the time window ('trong N giờ gần nhất'). It clearly distinguishes from siblings (web_search, fetch_page) by focusing on statistics rather than search or page fetch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage guidance: 'Dùng khi search trả kết quả kém hoặc chậm' (use when search returns poor or slow results), and states the purpose ('để biết nên đặt API key hay không' – to know whether to set an API key). It doesn't mention when not to use or alternatives, but the condition is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
web_searchB
Tìm kiếm trên web và trả về danh sách kết quả.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | "vi" để ưu tiên kết quả tiếng Việt, "en" cho tiếng Anh, "auto" để tự phát hiện theo truy vấn. | auto |
| count | No | Số kết quả mong muốn (1-20). | |
| query | Yes | Câu truy vấn tìm kiếm. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states the tool returns a list of results, which is basic behavioral info. It doesn't disclose details like whether results include snippets, URLs, or how results are ordered, but the output schema may cover some of this. The description is honest but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence in Vietnamese, front-loaded with the main action. It's efficient and easy to parse, though it could add a bit more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values are likely covered. The description is adequate for a simple search tool, but it doesn't mention any rate limits, pagination, or result ordering. Given the simplicity of the tool and full schema coverage, this is acceptable but not exceptional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description adds no additional meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Tìm kiếm trên web' (search the web) and returns a list of results. It distinguishes itself from siblings like fetch_page (which fetches a page) and search_stats (which returns statistics), though it doesn't explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for general web searching, and the lang parameter gives context for language preference. However, it doesn't explicitly state when to use this tool vs fetch_page or search_stats, nor does it mention any exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v0.1.0- First observed
fetch_page - First observed
search_stats - First observed
web_search
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
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.
Scrape, crawl and search the web for AI agents via MCP.
Serper MCP — wraps the Serper Google Search API (serper.dev)
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables web search through Exa or Parallel APIs for MCP-compatible AI clients like Cursor and Claude Code.13 npm1MIT
- 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.59 npm13MIT
- AlicenseAqualityBmaintenanceEnables AI agents to perform multi-engine web search, fetch web pages, and extract clean Markdown content via MCP, with no API keys required.392 PyPI8MIT
- AlicenseNot gradedqualityBmaintenanceEnables web search and scraping through MCP, running locally with courtesy rate limiting and caching.20 npmISC