Skip to main content
Glama
quangnx99

web-search-mcp

by quangnx99

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-mcp

Tools

Tool

Mô tả

web_search(query, count=5, lang="auto")

Tìm kiếm web, trả về title/url/snippet

fetch_page(url, max_chars=20000)

Lấy nội dung trang dưới dạng markdown

search_stats()

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ả:

  1. Serper.dev — Google SERP, nhanh nhất (~0.5s). Chỉ dùng nếu có SERPER_API_KEY.

  2. Tavily — search tối ưu cho LLM. Chỉ dùng nếu có TAVILY_API_KEY.

  3. free — qua ddgs, 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

auto

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. ddgs giới hạn số engine chạy song song bằng min(số_provider, ceil(max_results/10) + 1). Với count=5 mặ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 được ddgs shuffle mỗi lượt nên lần thử lại thường bốc được tổ hợp khác.

  • bing không phải backend hợp lệ. Danh sách thật: brave, duckduckgo, google, grokipedia, mojeek, startpage, wikipedia, yahoo, yandex. bing chỉ là provider nằm dưới duckduckgo/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ú

FREE_BACKENDS

auto

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

FREE_SEARCH_RETRIES

2

Số lần thử lại tầng free

SERPER_API_KEY

https://serper.dev — 2.500 query miễn phí

TAVILY_API_KEY

https://tavily.com — 1.000 credit/tháng

JINA_API_KEY

Tăng rate limit fetch_page

WEB_SEARCH_CACHE_TTL

3600

TTL cache search (giây)

FETCH_CACHE_TTL

3600

TTL cache fetch (giây)

MAX_RESULTS_PER_DOMAIN

2

Số URL tối đa giữ lại cho mỗi domain

WEB_SEARCH_CACHE_DB

thư mục cache của OS

Đường dẫn file cache.db

WEB_SEARCH_CACHE_MAX_ENTRIES

500

Số entry cache tối đa giữ trước khi trim

WEB_SEARCH_STATS_MAX_ROWS

1000

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 qua uvx/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 ... ✔ Connected

Hoặ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-mcp

Gó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-free

Trên Windows không cần bọc cmd /c: uv/uvx.exe thật.

Tên gọi: distribution trên PyPI là web-search-mcp-free — tên web-search-mcpwebsearch-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 alias web-search-mcp-freeuvx <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-free

Hoặ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-mcp

CLI 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 doctor

Test

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_backends lọc tên sai (bing) và rơi về auto khi không còn gì hợp lệ

  • retry của free_search, kể cả khi engine timeout

  • _is_binary chặ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ân

  • thứ tự fallback của fetch_page, và không cache nội dung lỗi

  • cache: 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/Tavily

  • dedupe domain: giữ tối đa 2 URL/domain, ưu tiên đa dạng

Giới hạn đã biết

  • cache.db chỉ trim bản ghi cũ khi vượt ngưỡng, không có vacuum định kỳ.

Available Tools

3 tools
fetch_pageA

Lấy nội dung đầy đủ của một trang web dưới dạng markdown.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesĐịa chỉ trang cần đọc.
max_charsNoSố ký tự tối đa trả về (cắt bớt nếu vượt quá).

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
hoursNoKhoảng thời gian thống kê (giờ).

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedfetch_page
    • First observedsearch_stats
    • First observedweb_search

TDQS

A4/5.0

Scored across 3 tools

Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

Three tools is well-scoped for a web search server: search, fetch, and operational diagnostics. Each tool earns its place with no redundancy.

Completeness5/5

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

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers