SerpApi MCP

SerpApi MCP Server

Triển khai máy chủ Model Context Protocol (MCP) tích hợp với SerpApi để cung cấp kết quả công cụ tìm kiếm toàn diện và trích xuất dữ liệu.

Tính năng

• Tìm kiếm đa công cụ: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay và nhiều công cụ khác
• Tài nguyên công cụ tìm kiếm: Có thể truy cập lược đồ tham số cho từng công cụ thông qua tài nguyên MCP (xem Công cụ tìm kiếm)
• Dữ liệu thời tiết theo thời gian thực: Thời tiết theo vị trí cùng dự báo thông qua truy vấn tìm kiếm
• Dữ liệu thị trường chứng khoán: Thông tin tài chính doanh nghiệp và dữ liệu thị trường thông qua tích hợp tìm kiếm
• Xử lý kết quả linh hoạt: Tự động phát hiện và định dạng các loại kết quả khác nhau
• Chế độ phản hồi linh hoạt: Phản hồi JSON đầy đủ hoặc rút gọn
• Phản hồi JSON (mặc định): Đầu ra JSON có cấu trúc với chế độ đầy đủ hoặc rút gọn
• Phản hồi Markdown: Giảm trung bình 50% lượng token sử dụng và hơn 90% với các API có JSON lồng nhau phức tạp.
• Giao diện tương tác (MCP Apps): Các công cụ search_table và search_dashboard tùy chọn, hiển thị kết quả dưới dạng giao diện tương tác trên các máy chủ hỗ trợ
• Tiện ích Claude Desktop: Cài đặt cục bộ chỉ bằng một cú nhấp từ MCP Bundle (.mcpb), xem bên dưới

Bắt đầu nhanh

SerpApi MCP Server có sẵn dưới dạng dịch vụ lưu trữ tại mcp.serpapi.com. Để kết nối, bạn cần cung cấp khóa API. Bạn có thể tìm khóa API trên bảng điều khiển SerpApi.

Bạn có thể cấu hình Claude Desktop để sử dụng máy chủ lưu trữ:

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

Bạn cũng có thể thêm máy chủ lưu trữ vào các ứng dụng MCP sau:

OpenClaw

openclaw mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp --transport streamable-http

Claude Code

claude mcp add --transport http serpapi https://mcp.serpapi.com/mcp --header "Authorization: Bearer YOUR_SERPAPI_API_KEY"

Hermes

hermes mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp

Codex (đọc khóa từ SERPAPI_API_KEY trong shell của bạn)

codex mcp add serpapi --url https://mcp.serpapi.com/mcp --bearer-token-env-var SERPAPI_API_KEY

Tự lưu trữ

git clone https://github.com/serpapi/serpapi-mcp.git
cd serpapi-mcp
uv sync && uv run src/server.py

Cấu hình Claude Desktop:

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "http://localhost:8000/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

Lấy khóa API: serpapi.com/manage-api-key

Tiện ích Claude Desktop (MCP bundle)

Để cài đặt cục bộ chỉ bằng một cú nhấp, hãy tải bundle .mcpb từ bản phát hành mới nhất và mở bằng Claude Desktop (hoặc kéo thả vào Settings → Extensions). Claude Desktop sẽ yêu cầu khóa API SerpApi trong quá trình cài đặt, lưu khóa dưới dạng cài đặt nhạy cảm và chạy máy chủ cục bộ qua stdio. Tiện ích sẽ cài đặt Python và các phần phụ thuộc bằng uv trong quá trình cài đặt. Bundle này hoạt động trên macOS, Windows và Linux.

Điểm vào stdio tương tự hoạt động với mọi máy chủ MCP cục bộ khởi chạy máy chủ dưới dạng tiến trình con:

{
  "mcpServers": {
    "serpapi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/serpapi-mcp", "--frozen", "--no-dev", "src/stdio.py"],
      "env": { "SERPAPI_API_KEY": "YOUR_SERPAPI_API_KEY" }
    }
  }
}

Xác thực

Có hai phương thức được hỗ trợ:

• Dựa trên header: Authorization: Bearer YOUR_API_KEY (khuyến nghị: khóa không xuất hiện trong URL và nhật ký)
• Dựa trên đường dẫn: /YOUR_API_KEY/mcp, dành cho các ứng dụng không thể thiết lập header

Ví dụ:

# Header-based
curl "https://mcp.serpapi.com/mcp" -H "Authorization: Bearer your_key" -d '...'

# Path-based
curl "https://mcp.serpapi.com/your_key/mcp" -d '...'

Không cần khóa để kết nối, liệt kê công cụ hoặc đọc tài nguyên. search và các công cụ App cần khóa; nếu không có khóa, chúng sẽ trả về lỗi.

Công cụ tìm kiếm

Máy chủ MCP có một công cụ tìm kiếm chính hỗ trợ tất cả công cụ và loại kết quả của SerpApi. Bạn có thể tìm tất cả tham số hiện có trong tài liệu tham khảo API SerpApi. Lược đồ tham số của từng công cụ cũng được cung cấp dưới dạng tài nguyên MCP: serpapi://engines (chỉ mục) và serpapi://engines/<engine>. Các ứng dụng hỗ trợ hoàn tất đối số có thể yêu cầu gợi ý tên công cụ cho serpapi://engines/{engine_name}. Ví dụ: tiền tố google_f sẽ gợi ý các mã định danh công cụ phù hợp. Tính năng này hoàn tất tham số URI tài nguyên, không phải các truy vấn tìm kiếm tùy ý.

Các tham số bạn có thể cung cấp tùy thuộc vào từng công cụ API. Dưới đây là một số tham số mẫu:

• params.q (bắt buộc): Truy vấn tìm kiếm
• params.engine: Công cụ tìm kiếm (mặc định: "google_light")
• params.location: Bộ lọc địa lý
• params.output: Định dạng phản hồi; bỏ qua để dùng JSON (mặc định), hoặc đặt thành "md" để dùng Markdown
• mode: Chế độ phản hồi; "compact" loại bỏ siêu dữ liệu khỏi JSON, còn Markdown được trả về nguyên trạng
• ...xem các tham số khác trong tài liệu tham khảo API SerpApi

Ví dụ:

{"name": "search", "arguments": {"params": {"q": "coffee shops", "location": "Austin, TX"}}}
{"name": "search", "arguments": {"params": {"q": "weather in London"}}}
{"name": "search", "arguments": {"params": {"q": "AAPL stock"}}}
{"name": "search", "arguments": {"params": {"q": "news"}, "mode": "compact"}}
{"name": "search", "arguments": {"params": {"q": "detailed search"}, "mode": "complete"}}
{"name": "search", "arguments": {"params": {"q": "news", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "amazon", "k": "mechanical keyboards", "amazon_domain": "amazon.com", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "google_scholar", "q": "retrieval augmented generation"}}}
{"name": "search", "arguments": {"params": {"engine": "youtube", "search_query": "how to make espresso"}}}
{"name": "search", "arguments": {"params": {"engine": "apple_app_store", "term": "habit tracker"}}}
{"name": "search", "arguments": {"params": {"engine": "ebay", "_nkw": "vintage mechanical keyboard"}}}

Các công cụ được hỗ trợ: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay và nhiều công cụ khác (xem serpapi://engines).

Loại kết quả: Hộp trả lời, kết quả tự nhiên, tin tức, hình ảnh, mua sắm — được tự động phát hiện và định dạng.

Phản hồi tìm kiếm giữ nguyên chuỗi MCP structuredContent.result hiện có và đưa cùng chuỗi đó vào nội dung văn bản. Với đầu ra JSON, result chứa JSON đã tuần tự hóa; các ứng dụng hiện có vẫn có thể phân tích nội dung bằng JSON.parse(response.structuredContent.result). Với đầu ra Markdown, trường này chứa Markdown nguyên trạng. Lỗi và thao tác bị hủy sử dụng cùng cấu trúc bao bọc. Lỗi thực thi tìm kiếm đặt isError: true; các ứng dụng dùng call_tool() cấp cao của FastMCP nên xử lý ToolError, hoặc dùng call_tool_mcp() để kiểm tra cờ kết quả. Xem kết quả công cụ MCP.

search sử dụng danh mục công cụ và các quy tắc riêng của từng công cụ để xác định tham số còn thiếu. Các ứng dụng hỗ trợ MCP 2026-07-28 sẽ nhận được biểu mẫu trước khi chạy tìm kiếm. Câu trả lời được chấp nhận sẽ được xác thực; nếu từ chối hoặc hủy, tìm kiếm sẽ không chạy. Các ứng dụng cũ và ứng dụng không hỗ trợ yêu cầu nhập liệu qua biểu mẫu sẽ nhận được lỗi liệt kê các tham số còn thiếu để tác nhân có thể hỏi trong cuộc trò chuyện. Xem yêu cầu nhập liệu MCP.

• Google Flights: mã định danh điểm đi và điểm đến, ngày khởi hành và ngày về đối với chuyến khứ hồi. Ngày và mã định danh sân bay sẽ được kiểm tra. Tìm kiếm dựa trên token, hành trình nhiều thành phố và selected_flights_json vẫn giữ nguyên cách hoạt động hiện có.
• Google Hotels: điểm đến hoặc truy vấn khách sạn, ngày nhận phòng và ngày trả phòng. Ngày trả phòng phải sau ngày nhận phòng. Số lượng khách và các bộ lọc tùy chọn khác giữ nguyên giá trị do bên gọi cung cấp hoặc dùng giá trị mặc định của API.
• Google Maps Directions: địa chỉ điểm đi và điểm đến còn thiếu. Tọa độ hoặc ID dữ liệu địa điểm đã cung cấp sẽ đáp ứng yêu cầu cho điểm cuối tương ứng.
• Các công cụ khác trong danh mục sử dụng những trường bắt buộc riêng, chẳng hạn như search_query của YouTube, find_loc của Yelp và k của Amazon. Quy tắc của từng công cụ tính đến các giá trị mặc định và phương án thay thế đã biết, bao gồm nút danh mục Amazon, danh mục eBay và tìm kiếm trích dẫn Google Scholar.

Nếu câu trả lời làm phát sinh yêu cầu khác, công cụ sẽ liệt kê các trường còn lại để tác nhân cung cấp trong một lệnh gọi mới. Biểu mẫu hỗ trợ trường chuỗi, số, boolean và lựa chọn đơn; các trường phức tạp không được hỗ trợ sẽ trả về lỗi tham số còn thiếu. Các công cụ không xác định sẽ được chuyển tiếp đến SerpApi.

Công cụ trích xuất

Công cụ extract đọc các trang web và trả về nội dung dưới dạng JSON có cấu trúc hoặc Markdown. Bạn có thể trích xuất một trang, tìm URL trên một trang web hoặc thu thập dữ liệu từ nhiều trang. Tìm tất cả tham số hiện có trong tài liệu tham khảo API Extract hoặc tài nguyên serpapi://engines/extract.

Một số tham số bạn có thể cung cấp:

• params.url (bắt buộc): URL trang hoặc trang web
• params.mode: Chế độ trích xuất; "scrape" (mặc định) đọc một trang, "map" tìm URL và "crawl" trích xuất nhiều trang
• params.include_markdown: Đưa nội dung trang vào dưới dạng Markdown; mặc định là true đối với scrape và crawl, hoặc đặt thành false để tắt
• params.output: Định dạng phản hồi; mặc định là "json" ở chế độ đầy đủ và "md" ở chế độ rút gọn. Đặt rõ để ghi đè định dạng.
• params.max_pages: Số trang tối đa cần crawl, bao gồm trang bắt đầu (mặc định: 10, tối đa: 100)
• params.json_restrictor: Chọn các trường cần trả về, chẳng hạn như "markdown,error"
• mode: Chế độ phản hồi; "complete" (mặc định) trả về toàn bộ phản hồi. "compact" mặc định trả về Markdown gốc. Khi chỉ định rõ params.output="json", thao tác trích xuất một trang ở chế độ JSON rút gọn sẽ giữ trường cấp cao nhất markdown nếu có và giữ lại lỗi API. Các phản hồi không có Markdown, bao gồm kết quả được chuyển hướng sang công cụ khác, vẫn giữ dữ liệu nhưng đã loại bỏ siêu dữ liệu. Các giá trị params.json_restrictor được chỉ định rõ và params.include_markdown=false được ưu tiên khi dùng JSON. Với map và crawl, JSON rút gọn sẽ loại bỏ siêu dữ liệu. Đầu ra Markdown được trả về nguyên trạng.

Ví dụ:

{"name": "extract", "arguments": {"params": {"url": "https://example.com"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com"}, "mode": "compact"}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "output": "md"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "map"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "crawl", "max_pages": 2}}}

Để nhận nội dung của một trang dưới dạng Markdown gốc, hãy dùng mode="compact". Thêm params.output="json" để nhận JSON chứa trường markdown. JSON đầy đủ mặc định bao gồm trường này; JSON crawl bao gồm trường này trong từng mục pages. Đặt params.output="json" và params.include_markdown=false để giữ lại các trường có cấu trúc còn lại mà không có Markdown.

Crawl tiêu tốn một lượt tìm kiếm cho mỗi trang được trích xuất thành công trong yêu cầu chưa có trong bộ nhớ đệm. Dùng params.max_pages để giới hạn số trang được trích xuất.

Giao diện tương tác (MCP apps)

Công cụ search mặc định trả về JSON. Với các máy chủ hỗ trợ phần mở rộng MCP Apps (SEP-1865), hai công cụ tùy chọn sẽ hiển thị kết quả dưới dạng giao diện tương tác ngay trong cuộc trò chuyện, nhờ đó JSON SERP dung lượng lớn không đi vào cửa sổ ngữ cảnh của mô hình:

• search_table: Kết quả tự nhiên dưới dạng bảng có thể sắp xếp và tìm kiếm.
• search_dashboard: Số liệu tổng hợp, biểu đồ phân tích nguồn và bảng kết quả có bảng chi tiết mở rộng khi nhấp.

Cả hai đều chấp nhận cùng params như search. Các máy chủ không hỗ trợ MCP Apps sẽ bỏ qua các công cụ này.

Khắc phục sự cố

• "Thiếu khóa API": Thêm khóa vào đường dẫn URL /{YOUR_KEY}/mcp hoặc header Bearer YOUR_KEY
• "Khóa không hợp lệ": Xác minh tại serpapi.com/dashboard
• "Vượt quá giới hạn tốc độ": Chờ hoặc nâng cấp gói SerpApi
• "Không có kết quả": Thử truy vấn hoặc công cụ khác

Chính sách quyền riêng tư

• Được gửi: chỉ các tham số mà máy chủ MCP chuyển cho lệnh gọi công cụ. Máy chủ không bao giờ thấy phần còn lại của cuộc trò chuyện, tệp, bộ nhớ hoặc lịch sử trên máy chủ.
• Được chuyển tiếp: mỗi lượt tìm kiếm được gửi đến serpapi.com cùng khóa API của bạn; kết quả được trả về nguyên trạng. Xem Chính sách quyền riêng tư của SerpApi để biết cách SerpApi xử lý các lượt tìm kiếm và tài khoản.
• Được lưu giữ: mcp.serpapi.com ghi lại số liệu yêu cầu (phương thức, mã trạng thái, thời lượng) và không lưu truy vấn hay kết quả. Khóa trong đường dẫn URL có thể xuất hiện trong nhật ký yêu cầu, vì vậy hãy ưu tiên dùng header.
• Bundle cục bộ: tiện ích Claude Desktop chạy trên máy của bạn, giữ khóa trong phần cài đặt của Claude Desktop và gọi trực tiếp serpapi.com. Không có dữ liệu nào đi qua mcp.serpapi.com.
• Liên hệ: privacy@serpapi.com, hoặc mở một vấn đề.

Đóng góp

Xem CONTRIBUTING.md để biết cách thiết lập môi trường phát triển, các lệnh làm mới lược đồ, kiểm thử, tạo Docker và MCP Bundle cũng như phát hành.

Giấy phép

Giấy phép MIT - xem tệp LICENSE để biết chi tiết.