# Web search MCP server cho Claude Code, Claude Desktop, Cursor và các MCP client khác

> Web search MCP server cho Claude Code, Claude Desktop và Cursor: một file Python ngắn với tool search_web và read_urls, đăng ký bằng một lệnh. Không cần KYC.

- URL: https://llmwebsearch.com/vi/docs/mcp/
- Cập nhật lần cuối: 2026-10-22
- Đơn vị phát hành: LLMWebSearch (https://llmwebsearch.com)

Cung cấp cho bất kỳ MCP client nào hai tool: `search_web`, trả về các nguồn đã xếp hạng với các trang hàng đầu đã được đọc sẵn, và `read_urls`, đọc các liên kết mà model đã có. Server là một file Python chạy trên máy của bạn, với khóa của bạn trong biến môi trường của nó.

**Trả lời nhanh — Làm sao để thêm một web search MCP server vào Claude Code hoặc Claude Desktop?**

Lưu server Python ngắn trên trang này, server này cung cấp các tool `search_web` và `read_urls` gọi **LLMWebSearch**, sau đó đăng ký nó bằng `claude mcp add` hoặc trong `claude_desktop_config.json`, với khóa của bạn trong `env`. Model sau đó có thể tìm kiếm trên web trực tiếp và đọc các trang hàng đầu dưới dạng Markdown. Mỗi tìm kiếm tốn 1 credit, từ 1,20 US$/1K lượt tìm kiếm tính đến tháng 10 năm 2026. Không cần KYC; thanh toán bằng crypto.

## Tổng quan về MCP server

| Thuộc tính | Giá trị |
| --- | --- |
| Ngôn ngữ | Python 3.10+, với các package `mcp` và `httpx` |
| Transport | stdio: client khởi chạy server như một tiến trình cục bộ |
| Tool 1 | `search_web(query, max_results=5, read=3)` → các nguồn được đánh số với URL và nội dung trang |
| Tool 2 | `read_urls(urls)` → nội dung chính của 1 đến 20 trang đã biết |
| Tên | Không phải `web_search` hay `web_fetch`: Claude Code và OpenClaw đã có sẵn các tool với những tên đó |
| Key | Đọc từ `LLMWEBSEARCH_API_KEY` trong biến môi trường của server |
| Thanh toán | Một credit trả cho một lượt tìm kiếm: tối đa 20 kết quả được xếp hạng, với nội dung của 3 trang đầu được đọc và trả về dưới dạng Markdown. Đọc từ 4 đến 10 trang thì tính 2 credit. Lượt gọi kết thúc bằng lỗi không tốn gì. Đọc các trang mà bạn đã có URL tốn 1 credit cho mỗi nhóm 3 trang bắt đầu được trả về kèm nội dung, tối đa 20 URL mỗi lượt gọi; các URL bị từ chối hoặc thất bại không được tính |

## Vì sao các tool được gọi là search_web và read_urls?

Vì hai tool trùng tên sẽ gây nhầm lẫn cho client và model. Claude Code và OpenClaw đều có các tool tích hợp tên là `web_search` và `web_fetch`. Tên khác biệt, với mô tả rõ ràng, giúp model chọn tool của chúng tôi một cách có chủ đích và giúp bạn phân biệt các lệnh gọi trong log.

Cả hai tool đều trả về văn bản, không phải JSON thô. Mỗi nguồn bắt đầu bằng một số, một tiêu đề và URL của nó, để model có thể trích dẫn `[1]` hoặc `[2]` và người đọc có thể kiểm tra trang.

*llmwebsearch_mcp.py*

```python
import os

import httpx
from mcp.server.fastmcp import FastMCP

BASE = "https://llmwebsearch.com/api/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["LLMWEBSEARCH_API_KEY"]}
mcp = FastMCP("llmwebsearch")


def _call(path: str, body: dict) -> dict:
    resp = httpx.post(BASE + path, json=body, headers=HEADERS, timeout=90)
    data = resp.json()
    if resp.status_code != 200:
        err = data.get("error", {})
        raise RuntimeError(err.get("code", str(resp.status_code)) + ": " + err.get("message", ""))
    return data


def _page(n: int, item: dict) -> str:
    head = f"[{n}] {item.get('title') or item['url']}\n{item['url']}\n"
    if item.get("content_status") == "ok":
        return head + item["content"]
    return head + "(not read: " + item.get("content_status", "unknown") + ") " + item.get("snippet", "")


@mcp.tool()
def search_web(query: str, max_results: int = 5, read: int = 3) -> str:
    """Search the live web and return numbered sources; the first `read` pages include their text.

    Use it for current facts, documentation and news. Cite sources by their number.
    """
    body = {"q": query, "max_results": max(1, min(max_results, 20)), "read": max(0, min(read, 10)), "max_chars": 5000}
    data = _call("/search", body)
    return "\n\n".join(_page(i, r) for i, r in enumerate(data["results"], start=1))


@mcp.tool()
def read_urls(urls: list[str]) -> str:
    """Read 1 to 20 public web pages whose URLs you already have and return their main text."""
    data = _call("/extract", {"urls": urls[:20], "max_chars": 12000})
    return "\n\n".join(_page(i, r) for i, r in enumerate(data["results"], start=1))


if __name__ == "__main__":
    mcp.run()

```

## Làm sao để cài đặt và kiểm thử server?

Tạo một virtual environment, cài `mcp` và `httpx`, rồi lưu file ở trên. `mcp` là SDK Python chính thức của Model Context Protocol; lớp `FastMCP` của nó biến các hàm Python có type thành tool và dùng mỗi docstring làm mô tả của tool.

Khởi chạy file một lần từ terminal với khóa của bạn đã được đặt. Sau đó nó chờ client một cách lặng lẽ trên standard input, nghĩa là nó hoạt động; dừng nó bằng Ctrl+C. Lỗi từ API được ném ra dưới dạng lỗi tool kèm mã lỗi, để model thấy `rate_limited` hoặc `insufficient_credits` bằng ngôn ngữ thường.

*Cài đặt và khởi chạy một lần*

```bash
python -m venv .venv
. .venv/bin/activate
pip install "mcp[cli]" httpx
LLMWEBSEARCH_API_KEY="your-key" python llmwebsearch_mcp.py
```

## Làm sao để thêm nó vào Claude Code?

Dùng `claude mcp add`. Tài liệu của Claude Code đưa ra dạng `claude mcp add [options] <name> -- <command> [args...]`: các tùy chọn của riêng nó đứng trước, sau đó là hai dấu gạch ngang, rồi đến lệnh khởi chạy server. Biến môi trường đặt trong `--env KEY=value`, và ít nhất một tùy chọn khác, chẳng hạn `--transport stdio`, phải nằm giữa `--env` và tên server.

Thêm `--scope user` để server có sẵn trong tất cả dự án của bạn; scope mặc định, `local`, chỉ bao phủ dự án hiện tại. Dùng đường dẫn tuyệt đối cho Python của virtual environment và cho file server.

*Đăng ký server trong Claude Code*

```bash
claude mcp add --env LLMWEBSEARCH_API_KEY=your-key --transport stdio --scope user llmwebsearch \
  -- /home/you/llmwebsearch/.venv/bin/python /home/you/llmwebsearch/llmwebsearch_mcp.py
```

## Làm thế nào để thêm nó vào Claude Desktop và các client khác?

Claude Desktop đọc các server từ `claude_desktop_config.json`, trong mục `mcpServers`. Đặt tên cho server, nhập command, các đối số của nó và một object `env` chứa khóa, sau đó khởi động lại ứng dụng; `search_web` và `read_urls` sẽ xuất hiện trong danh sách công cụ.

Các MCP client khác, chẳng hạn Cursor, cũng yêu cầu đúng ba thứ đó trong phần cài đặt MCP riêng của chúng: một command, các đối số và biến môi trường. Khóa không bao giờ xuất hiện trong đối số của công cụ hay trong cuộc hội thoại.

*claude_desktop_config.json*

```json
{
  "mcpServers": {
    "llmwebsearch": {
      "command": "/home/you/llmwebsearch/.venv/bin/python",
      "args": ["/home/you/llmwebsearch/llmwebsearch_mcp.py"],
      "env": { "LLMWEBSEARCH_API_KEY": "your-key" }
    }
  }
}
```

## Làm thế nào để giữ các lượt tìm kiếm rẻ và ngắn gọn?

Hãy dặn model cách tìm kiếm trong phần hướng dẫn của bạn: một hoặc hai lượt tìm kiếm cho mỗi câu hỏi, sau đó chỉ đọc thêm nếu các nguồn mâu thuẫn nhau. Server đã giới hạn mỗi trang ở 5.000 ký tự trong `search_web` và 12.000 trong `read_urls`; hãy giảm các con số đó cho các model nhỏ.

Mỗi lần gọi `search_web` với `read` tối đa 3 là một credit. Một trợ lý chạy 40 lượt tìm kiếm mỗi ngày dùng khoảng 1.200 credit một tháng, vậy 5.000 lượt tìm kiếm (9,25 US$) dùng được khoảng bốn tháng. Credit tìm kiếm không có ngày hết hạn: phần bạn không dùng trong tháng này vẫn còn đó vào năm sau.

## Model thấy gì khi không thể đọc một trang?

Nguồn đó vẫn hiện ra, kèm số thứ tự, tiêu đề và URL, tiếp theo là lý do trong ngoặc và đoạn trích của kết quả tìm kiếm. Trình đọc của chúng tôi tôn trọng robots.txt: nó tự giới thiệu là LLMWebSearch, tuân theo các quy tắc mà một trang viết cho nó hoặc cho tất cả robot, và bỏ qua nội dung của bất kỳ trang nào nó không được phép đọc. Khi một trang từ chối trình đọc của chúng tôi, kết quả trả về không có nội dung kèm trạng thái của trang: chúng tôi không bao giờ giải CAPTCHA, đăng nhập vào tài khoản hay lách qua một chặn chặn hoặc paywall. Model sau đó có thể dựa vào các nguồn khác hoặc nói rằng một trang không khả dụng.

## MCP server: các câu hỏi thường gặp

### Có gói MCP chính thức hay endpoint được host sẵn của LLMWebSearch không?

Không. Tệp trên trang này chính là phần tích hợp: khoảng 50 dòng mà bạn có thể đọc và sửa. Nó chạy trên máy của bạn, và khóa của bạn chỉ được gửi đến API của chúng tôi.

### Tôi có nên tắt tính năng tìm kiếm web tích hợp của Claude Code không?

Không cần. Cả hai có thể cùng bật; phần mô tả cho model biết mỗi bên làm gì. Hãy giữ cái của chúng tôi khi bạn muốn có văn bản trang trong kết quả, giá cố định cho mỗi lượt tìm kiếm, hoặc một nơi lưu nhật ký tìm kiếm của bạn.

### Tôi có thể dùng nó với OpenClaw không?

Có, dưới dạng một MCP server đăng ký bằng `openclaw mcp add`. [Trang OpenClaw](https://llmwebsearch.com/vi/docs/openclaw/) đưa ra command và giải thích cách nó hoạt động song song với các nhà cung cấp tìm kiếm tích hợp của OpenClaw.

### Server có lưu các lượt tìm kiếm của tôi không?

Không. Nó không giữ gì giữa các lần gọi. Về phía chúng tôi, Chúng tôi không huấn luyện bất kỳ model nào trên truy vấn của bạn hay trên những gì API trả về, và chúng tôi không thêm quy tắc riêng nào chống lại việc lưu trữ kết quả; quyền của các trang có nội dung bạn đọc vẫn áp dụng.

## Nguồn

1. [Kết nối Claude Code với các công cụ qua MCP](https://code.claude.com/docs/en/mcp) — Claude Code docs (read 2026-10-22)

---

LLMWebSearch: LLMWebSearch là một web search API cho AI agent, trả về kết quả đã xếp hạng kèm nội dung của các trang hàng đầu ở định dạng Markdown, thanh toán bằng crypto mà không cần tải lên giấy tờ tùy thân. Credit trả trước từ 1,20 US$/1K lượt tìm kiếm không bao giờ hết hạn. Không cần KYC — không ID, không selfie, không giấy tờ. Thanh toán bằng crypto.