SerpApi MCP

SerpApi MCP Server

Máy chủ Model Context Protocol (MCP) triển khai tích hợp với SerpApi để lấy kết quả 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 hơn nữa
• Tài nguyên công cụ: Lược đồ tham số theo từng công cụ có sẵn qua tài nguyên MCP (xem Công cụ Tìm kiếm)
• Dữ liệu thời tiết thời gian thực: Thời tiết theo vị trí kèm dự báo qua truy vấn tìm kiếm
• Dữ liệu thị trường chứng khoán: Tài chính doanh nghiệp và dữ liệu thị trường qua tích hợp tìm kiếm
• Xử lý kết quả động: 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 gọn nhẹ
• Phản hồi JSON (mặc định): Đầu ra JSON có cấu trúc với chế độ đầy đủ hoặc gọn nhẹ
• Phản hồi Markdown: Giảm mức sử dụng token trung bình 50% và hơn 90% đối với các API có JSON lồng nhau phức tạp.
• Giao diện tương tác (Ứng dụng MCP): 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 trong các máy chủ hỗ trợ
• Tiện ích mở rộng Claude Desktop: Cài đặt cục bộ một lần từ Gói MCP (.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 của mình 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 máy khách 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 của bạn: serpapi.com/manage-api-key

Tiện ích mở rộng Claude Desktop (Gói MCP)

Để cài đặt cục bộ một lần, hãy tải gói .mcpb từ bản phát hành mới nhất (hoặc xây dựng như bên dưới) và mở bằng Claude Desktop (hoặc kéo thả vào Cài đặt → Tiện ích mở rộng). Claude Desktop yêu cầu khóa API SerpApi của bạn trong quá trình cài đặt, lưu trữ dưới dạng cài đặt nhạy cảm và chạy máy chủ cục bộ qua stdio. Gói sử dụng thời gian chạy MCPB uv: nó chỉ bao gồm mã nguồn, pyproject.toml và uv.lock, và Claude Desktop cung cấp Python cùng các phụ thuộc khóa tại thời điểm cài đặt bằng uv, do đó không có gì được đóng gói và một gói hoạt động trên macOS, Windows và Linux.

uv run mcpb/build.py   # needs Node.js for the MCPB CLI; writes dist/serpapi-mcp-<version>.mcpb

Mọi thứ liên quan đến gói nằm trong mcpb/, cùng với .mcpbignore ở thư mục gốc dự án. Quá trình xây dựng tạo lại lược đồ công cụ từ SerpApi Playground (--no-rebuild-engines đóng gói engines/ từ cây làm việc thay thế), xác thực mcpb/manifest.json, đóng gói các tệp theo dõi git trừ .mcpbignore với manifest ở thư mục gốc gói, sau đó cài đặt vào thư mục tạm và khởi động qua stdio để đảm bảo hoạt động (--no-smoke bỏ qua bước cuối này). Gói chỉ được xây dựng tại thời điểm phát hành: đẩy thẻ v<version> chạy quy trình phát hành, chạy bộ kiểm thử rồi triển khai máy chủ lưu trữ, xuất bản mục nhập MCP Registry và xây dựng gói đính kèm vào bản phát hành GitHub. Các yêu cầu kéo chạy kiểm thử manifest và điểm vào stdio trong tests/test_mcpb.py nhưng không đóng gói.

Đ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

Hai phương pháp được hỗ trợ:

• Dựa trên tiêu đề: 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 máy khách không thể đặt tiêu đề

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ụ Ứng dụng cần khóa và trả về lỗi nếu thiếu.

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ố có sẵn trên tài liệu tham khảo API SerpApi. Lược đồ tham số công cụ cũng được hiển thị dưới dạng tài nguyên MCP: serpapi://engines (chỉ mục) và serpapi://engines/<engine>. Máy khách hỗ trợ hoàn thành đố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 gợi ý mã định danh công cụ khớp. Điều này hoàn thành tham số URI tài nguyên, không phải truy vấn tìm kiếm tùy ý.

Các tham số bạn có thể cung cấp cụ thể cho từng công cụ API. Một số tham số mẫu được cung cấp bên dưới:

• 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 để nhận JSON (mặc định) hoặc đặt thành "md" để nhận Markdown
• mode: Chế độ phản hồi; "compact" loại bỏ siêu dữ liệu khỏi JSON, trong khi Markdown được trả về nguyên trạng
• ...xem các tham số khác trên 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ông cụ được hỗ trợ: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay và nhiều hơn nữa (xem serpapi://engines).

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

Phản hồi tìm kiếm giữ nguyên chuỗi structuredContent.result MCP hiện có và bao gồm cùng chuỗi trong nội dung văn bản. Đối với đầu ra JSON, result chứa JSON đã tuần tự hóa; máy khách hiện có thể tiếp tục phân tích bằng JSON.parse(response.structuredContent.result). Đối với đầu ra Markdown, nó chứa Markdown không thay đổi. Lỗi và hủy bỏ sử dụng cùng trình bao bọc. Lỗi thực thi tìm kiếm đặt isError: true; máy khách sử 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à quy tắc cụ thể theo công cụ để xác định tham số còn thiếu. Máy khách hỗ trợ MCP 2026-07-28 nhận 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; từ chối hoặc hủy bỏ không chạy tìm kiếm. Máy khách cũ và máy khách không có khả năng thu thập biểu mẫu nhận lỗi liệt kê tham số còn thiếu để tác nhân hỏi trong hội thoại. Xem yêu cầu đầu vào MCP.

• Google Flights: mã định danh khởi hành và đến, ngày khởi hành và ngày về cho chuyến khứ hồi. Ngày và mã sân bay được kiểm tra. Tìm kiếm dựa trên token, hành trình nhiều chặng và selected_flights_json giữ nguyên hành vi hiện tại.
• Google Hotels: truy vấn điểm đến hoặc 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ố khách và bộ lọc tùy chọn khác giữ giá trị của người gọi hoặc mặc định của API.
• Google Maps Directions: thiếu địa chỉ bắt đầu và điểm đến. Tọa độ hoặc mã dữ liệu địa điểm đã cung cấp đáp ứng điểm cuối tương ứng.
• Các công cụ danh mục khác sử dụng trường bắt buộc của chúng, như search_query của YouTube, find_loc của Yelp và k của Amazon. Quy tắc công cụ tính đến mặc định và lựa chọ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.

Biểu mẫu được tạo từ đối số gốc trên mỗi yêu cầu. Nó không sử dụng requestState hoặc lưu trữ tiếp tục cục bộ tiến trình, do đó lần thử lại có thể chạy trên bản sao khác mà không cần khóa bảo vệ trạng thái chia sẻ. Xác thực được áp dụng trên mọi yêu cầu HTTP và chỉ câu trả lời cho trường được yêu cầu được sử dụng. Nếu câu trả lời giới thiệu yêu cầu khác, công cụ liệt kê trường còn lại để tác nhân cung cấp trong lệnh gọi mới.

Để mở rộng tìm kiếm có hướng dẫn, thêm trường bắt buộc, mô tả, loại và tùy chọn vào tệp engines/<engine>.json của công cụ. Thêm mục nhập EngineInputRules trong src/engine_input_rules.py khi yêu cầu phụ thuộc vào tham số khác, mặc định hoặc lựa chọn thay thế. Trình xử lý MCP dùng chung trong src/search_input.py không cần nhánh cụ thể theo công cụ. Biểu mẫu hỗ trợ chuỗi, số, boolean và trường chọn đơn; trường phức tạp không được hỗ trợ nhận lỗi tham số còn thiếu. Công cụ không xác định chuyển qua SerpApi.

Giao diện tương tác (Ứng dụng MCP)

Công cụ search trả về JSON theo mặc định. Đối với máy chủ hỗ trợ tiện ích mở rộng MCP Apps (SEP-1865), hai công cụ tùy chọn hiển thị kết quả dưới dạng giao diện tương tác trực tiếp trong hội thoại, do đó JSON SERP lớn không bao giờ vào cửa sổ ngữ cảnh của mô hình:

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

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

Xem trước cục bộ mà không cần máy chủ MCP:

uv run fastmcp dev apps src/server.py

Phát triển

# Local development
uv sync && uv run src/server.py

# Docker
docker build -t serpapi-mcp . && docker run -p 8000:8000 serpapi-mcp

# Build the Claude Desktop extension (MCP Bundle); rebuilds engines, needs Node.js for the MCPB CLI
uv run mcpb/build.py

# Release: update pyproject.toml, server.json, mcpb/manifest.json and uv.lock together.
uv run --no-sync scripts/bump_version.py 2.0.0
# Review and commit the changes before tagging the release.
# Nothing ships on a plain push to main. The tag runs the release workflow, which runs the test
# suite and then deploys the hosted server, publishes server.json to the MCP Registry, and builds
# the MCP Bundle and attaches it to the GitHub release.
git tag v2.0.0 && git push origin v2.0.0

# Regenerate engine resources (Playground scrape)
python build-engines.py

# Testing with MCP Inspector
npx @modelcontextprotocol/inspector
# Configure: URL mcp.serpapi.com/YOUR_KEY/mcp, Transport "Streamable HTTP transport"

Xử lý sự cố

• "Thiếu khóa API": Bao gồm khóa trong đường dẫn URL /{YOUR_KEY}/mcp hoặc tiêu đề 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 của bạn
• "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áy chủ MCP chuyển đến lệnh gọi công cụ. Máy chủ không bao giờ thấy phần còn lại của hội thoại, tệp, bộ nhớ hoặc lịch sử trên máy chủ.
• Được chuyển tiếp: mỗi tìm kiếm đi đến serpapi.com với khóa API của bạn; kết quả trả về không thay đổi. Xem Chính sách quyền riêng tư SerpApi để biết cách SerpApi xử lý tìm kiếm và tài khoản.
• Được giữ: mcp.serpapi.com ghi 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 trữ truy vấn hoặc kết quả. Khóa trong đường dẫn URL có thể xuất hiện trong nhật ký yêu cầu, do đó hãy ưu tiên tiêu đề.
• Gói cục bộ: tiện ích mở rộng Claude Desktop chạy trên máy của bạn, giữ khóa trong cài đặt Claude Desktop và gọi serpapi.com trực tiếp. Không có gì đi qua mcp.serpapi.com.
• Liên hệ: privacy@serpapi.com hoặc mở vấn đề.

Đóng góp

1. Fork kho lưu trữ
2. Tạo nhánh tính năng của bạn: git checkout -b feature/amazing-feature
3. Cài đặt phụ thuộc: uv install
4. Thực hiện thay đổi của bạn
5. Cam kết thay đổi: git commit -m 'Add amazing feature'
6. Đẩy lên nhánh: git push origin feature/amazing-feature
7. Mở Yêu cầu kéo

Giấy phép

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