SerpApi MCP

SerpApi MCP Server

การใช้งานเซิร์ฟเวอร์ Model Context Protocol (MCP) ที่เชื่อมต่อกับ SerpApi สำหรับผลการค้นหาจากเครื่องมือค้นหาที่ครอบคลุมและการดึงข้อมูล

คุณสมบัติ

• การค้นหาหลายเครื่องมือ: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay และ อื่นๆ
• ทรัพยากรของเครื่องมือ: โครงสร้างพารามิเตอร์เฉพาะของแต่ละเครื่องมือสามารถเข้าถึงได้ผ่านทรัพยากร MCP (ดูเครื่องมือค้นหา)
• ข้อมูลสภาพอากาศแบบเรียลไทม์: สภาพอากาศตามตำแหน่งพร้อมพยากรณ์ผ่านคำค้นหา
• ข้อมูลตลาดหุ้น: ข้อมูลทางการเงินของบริษัทและข้อมูลตลาดผ่านการเชื่อมต่อการค้นหา
• การประมวลผลผลลัพธ์แบบไดนามิก: ตรวจจับและจัดรูปแบบผลลัพธ์ประเภทต่างๆ โดยอัตโนมัติ
• โหมดการตอบสนองที่ยืดหยุ่น: การตอบสนอง JSON แบบสมบูรณ์หรือแบบกระชับ
• การตอบสนอง JSON (ค่าเริ่มต้น): ผลลัพธ์ JSON ที่มีโครงสร้างพร้อมโหมดสมบูรณ์หรือกระชับ
• การตอบสนอง Markdown: ลดการใช้โทเค็นลงเฉลี่ย 50% และมากกว่า 90% สำหรับ API ที่มี JSON ซ้อนซับซ้อน
• UI แบบโต้ตอบ (แอป MCP): เครื่องมือ search_table และ search_dashboard แบบเลือกใช้ที่แสดงผลลัพธ์เป็น UI แบบโต้ตอบในโฮสต์ที่รองรับ
• ส่วนขยาย Claude Desktop: ติดตั้งในเครื่องได้ด้วยคลิกเดียวจาก MCP Bundle (.mcpb) ดูด้านล่าง

เริ่มต้นใช้งานอย่างรวดเร็ว

SerpApi MCP Server พร้อมใช้งานเป็นบริการโฮสต์ที่ mcp.serpapi.com ในการเชื่อมต่อ คุณต้องระบุคีย์ API คุณสามารถค้นหาคีย์ API ของคุณได้ที่ แดชบอร์ด SerpApi

คุณสามารถกำหนดค่า Claude Desktop เพื่อใช้เซิร์ฟเวอร์ที่โฮสต์:

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

คุณยังสามารถเพิ่มเซิร์ฟเวอร์ที่โฮสต์ไปยังไคลเอ็นต์ MCP เหล่านี้:

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 (อ่านคีย์จาก SERPAPI_API_KEY ในเชลล์ของคุณ)

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

การโฮสต์ด้วยตนเอง

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

กำหนดค่า Claude Desktop:

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

รับคีย์ API ของคุณ: serpapi.com/manage-api-key

ส่วนขยาย Claude Desktop (MCP Bundle)

สำหรับการติดตั้งในเครื่องด้วยคลิกเดียว ให้ดาวน์โหลดบันเดิล .mcpb จาก รุ่นล่าสุด (หรือสร้างตามด้านล่าง) และเปิดด้วย Claude Desktop (หรือลากไปวางบน การตั้งค่า → ส่วนขยาย) Claude Desktop จะขอคีย์ API SerpApi ของคุณระหว่างการติดตั้ง เก็บเป็นค่าการตั้งค่าที่ละเอียดอ่อน และรันเซิร์ฟเวอร์ในเครื่องผ่าน stdio บันเดิลใช้รันไทม์ MCPB uv: จัดส่งเฉพาะซอร์ส pyproject.toml และ uv.lock และ Claude Desktop จัดเตรียม Python และ dependencies ที่ล็อกไว้ด้วย uv ในเวลาติดตั้ง ดังนั้นจึงไม่มีสิ่งใดถูกบรรจุรวม และบันเดิลเดียวใช้งานได้บน macOS, Windows และ Linux

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

ทุกอย่างที่เกี่ยวข้องกับบันเดิลอยู่ใน mcpb/ รวมถึง .mcpbignore ที่รากของโปรเจกต์ การสร้างจะสร้างโครงสร้างเครื่องมือใหม่จาก SerpApi Playground (--no-rebuild-engines บันเดิล engines/ จาก working tree แทน) ตรวจสอบ mcpb/manifest.json แพ็คไฟล์ที่ติดตามด้วย git ลบ .mcpbignore พร้อม manifest ที่รากของบันเดิล จากนั้นติดตั้งลงในไดเรกทอรีชั่วคราวและเริ่มผ่าน stdio เพื่อให้แน่ใจว่าทำงานได้ (--no-smoke ข้ามขั้นตอนสุดท้ายนั้น) บันเดิลจะถูกสร้างเฉพาะเวลาปล่อยรุ่น: การพุชแท็ก v<version> จะรันเวิร์กโฟลว์การปล่อย ซึ่งรันชุดทดสอบ จากนั้นปรับใช้เซิร์ฟเวอร์ที่โฮสต์ เผยแพร่รายการ MCP Registry และสร้างบันเดิลและแนบไปกับการปล่อย GitHub Pull requests รันการทดสอบ manifest และ stdio entry point ใน tests/test_mcpb.py แต่ไม่แพ็คบันเดิล

entry point stdio เดียวกันทำงานกับโฮสต์ MCP ในเครื่องใดๆ ที่เปิดใช้เซิร์ฟเวอร์เป็นซับโพรเซส:

{
  "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" }
    }
  }
}

การรับรองความถูกต้อง

รองรับสองวิธี:

• ตามส่วนหัว: Authorization: Bearer YOUR_API_KEY (แนะนำ: คีย์ไม่อยู่ใน URL และบันทึก)
• ตามเส้นทาง: /YOUR_API_KEY/mcp สำหรับไคลเอ็นต์ที่ไม่สามารถตั้งค่าส่วนหัวได้

ตัวอย่าง:

# 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 '...'

ไม่จำเป็นต้องใช้คีย์ในการเชื่อมต่อ ดูรายการเครื่องมือ หรืออ่านทรัพยากร search และเครื่องมือแอปต้องใช้คีย์และจะส่งคืนข้อผิดพลาดหากไม่มี

เครื่องมือค้นหา

เซิร์ฟเวอร์ MCP มีเครื่องมือค้นหาหลักหนึ่งรายการที่รองรับเครื่องมือค้นหาและประเภทผลลัพธ์ทั้งหมดของ SerpApi คุณสามารถค้นหาพารามิเตอร์ที่มีทั้งหมดได้ที่ เอกสารอ้างอิง API SerpApi โครงสร้างพารามิเตอร์ของเครื่องมือยังแสดงเป็นทรัพยากร MCP: serpapi://engines (ดัชนี) และ serpapi://engines/<engine> ไคลเอ็นต์ที่รองรับ การเติมอาร์กิวเมนต์ สามารถขอคำแนะนำชื่อเครื่องมือสำหรับ serpapi://engines/{engine_name} ตัวอย่างเช่น คำนำหน้า google_f แนะนำตัวระบุเครื่องมือที่ตรงกัน ซึ่งจะเติมพารามิเตอร์ URI ของทรัพยากร ไม่ใช่คำค้นหาทั่วไป

พารามิเตอร์ที่คุณสามารถระบุได้จะเฉพาะเจาะจงสำหรับแต่ละเครื่องมือ API ตัวอย่างพารามิเตอร์บางส่วนมีดังนี้:

• params.q (จำเป็น): คำค้นหา
• params.engine: เครื่องมือค้นหา (ค่าเริ่มต้น: "google_light")
• params.location: ตัวกรองภูมิศาสตร์
• params.output: รูปแบบการตอบสนอง ละเว้นสำหรับ JSON (ค่าเริ่มต้น) หรือตั้งค่าเป็น "md" สำหรับ Markdown
• mode: โหมดการตอบสนอง "compact" ลบ metadata จาก JSON ในขณะที่ Markdown ถูกส่งคืนโดยไม่เปลี่ยนแปลง
• ...ดูพารามิเตอร์อื่นๆ ได้ที่ เอกสารอ้างอิง API SerpApi

ตัวอย่าง:

{"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"}}}

เครื่องมือที่รองรับ: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay และอื่นๆ (ดู serpapi://engines)

ประเภทผลลัพธ์: กล่องคำตอบ ผลลัพธ์อินทรีย์ ข่าว รูปภาพ ช้อปปิ้ง - ตรวจจับและจัดรูปแบบโดยอัตโนมัติ

การตอบสนองการค้นหาจะรักษาสตริง structuredContent.result MCP ที่มีอยู่และรวมสตริงเดียวกันในเนื้อหาข้อความ สำหรับผลลัพธ์ JSON result มี JSON ที่ซีเรียลไลซ์ ไคลเอ็นต์ที่มีอยู่สามารถแยกวิเคราะห์ต่อด้วย JSON.parse(response.structuredContent.result) สำหรับผลลัพธ์ Markdown จะมี Markdown ที่ไม่เปลี่ยนแปลง ข้อผิดพลาดและการยกเลิกใช้ wrapper เดียวกัน ความล้มเหลวในการดำเนินการค้นหาจะตั้งค่า isError: true ไคลเอ็นต์ที่ใช้ call_tool() ระดับสูงของ FastMCP ควรจัดการ ToolError หรือใช้ call_tool_mcp() เพื่อตรวจสอบแฟล็กผลลัพธ์ ดู ผลลัพธ์เครื่องมือ MCP

search ใช้แคตตาล็อกเครื่องมือและกฎเฉพาะเครื่องมือเพื่อระบุพารามิเตอร์ที่ขาดหายไป ไคลเอ็นต์ที่รองรับ MCP 2026-07-28 จะได้รับฟอร์มก่อนการค้นหาใดๆ คำตอบที่ยอมรับจะถูกตรวจสอบ การปฏิเสธหรือยกเลิกจะไม่รันการค้นหา ไคลเอ็นต์รุ่นเก่าและไคลเอ็นต์ที่ไม่มีการดึงฟอร์มจะได้รับข้อผิดพลาดที่แสดงรายการพารามิเตอร์ที่ขาดหายไป เพื่อให้เอเจนต์สามารถถามในการสนทนาได้ ดู คำขออินพุต MCP

• Google Flights: ตัวระบุต้นทางและปลายทาง วันที่ออกเดินทาง และวันที่กลับสำหรับเที่ยวบินไปกลับ วันที่และตัวระบุสนามบินจะถูกตรวจสอบ การค้นหาแบบโทเค็น การเดินทางหลายเมือง และ selected_flights_json ยังคงพฤติกรรมเดิม
• Google Hotels: คำค้นหาปลายทางหรือโรงแรม วันที่เช็คอิน และวันที่เช็คเอาท์ วันที่เช็คเอาท์ต้องตามหลังเช็คอิน จำนวนแขกและตัวกรองเพิ่มเติมอื่นๆ ใช้ค่าของผู้เรียกหรือค่าเริ่มต้นของ API
• Google Maps Directions: ที่อยู่เริ่มต้นและปลายทางที่ขาดหายไป พิกัดหรือ ID ข้อมูลสถานที่ที่ระบุแล้วจะตอบสนอง endpoint ที่เกี่ยวข้อง
• เครื่องมืออื่นๆ ในแคตตาล็อกใช้ฟิลด์ที่จำเป็น เช่น search_query ของ YouTube, find_loc ของ Yelp และ k ของ Amazon กฎของเครื่องมือคำนึงถึงค่าเริ่มต้นและทางเลือกที่ทราบ รวมถึงโหนดหมวดหมู่ Amazon หมวดหมู่ eBay และการค้นหาการอ้างอิง Google Scholar

ฟอร์มได้มาจากอาร์กิวเมนต์เดิมในแต่ละคำขอ ไม่ใช้ requestState หรือพื้นที่จัดเก็บต่อเนื่องของโพรเซส ดังนั้นการลองใหม่สามารถรันบน replica อื่นได้โดยไม่ต้องใช้คีย์ป้องกันสถานะร่วมกัน การรับรองความถูกต้องถูกใช้กับทุกคำขอ HTTP และใช้เฉพาะคำตอบสำหรับฟิลด์ที่ร้องขอ หากคำตอบแนะนำข้อกำหนดเพิ่มเติม เครื่องมือจะแสดงรายการฟิลด์ที่เหลือสำหรับเอเจนต์เพื่อระบุในการเรียกใหม่

เพื่อขยายการค้นหาแบบแนะนำ เพิ่มฟิลด์ที่จำเป็น คำอธิบาย ประเภท และตัวเลือกในไฟล์ engines/<engine>.json ของเครื่องมือ เพิ่มรายการ EngineInputRules ใน src/engine_input_rules.py เมื่อข้อกำหนดขึ้นอยู่กับพารามิเตอร์อื่น ค่าเริ่มต้น หรือทางเลือก ตัวจัดการ MCP ที่ใช้ร่วมกันใน src/search_input.py ไม่จำเป็นต้องมีสาขาเฉพาะเครื่องมือ ฟอร์มรองรับสตริง ตัวเลข บูลีน และฟิลด์เลือกเดียว ฟิลด์ซับซ้อนที่ไม่รองรับจะได้รับข้อผิดพลาดพารามิเตอร์ที่ขาดหายไป เครื่องมือที่ไม่รู้จักจะส่งผ่านไปยัง SerpApi

UI แบบโต้ตอบ (แอป MCP)

เครื่องมือ search ส่งคืน JSON โดยค่าเริ่มต้น สำหรับโฮสต์ที่รองรับ ส่วนขยายแอป MCP (SEP-1865) เครื่องมือแบบเลือกใช้สองรายการจะแสดงผลลัพธ์เป็น UI แบบโต้ตอบโดยตรงในการสนทนา ดังนั้น SERP JSON จำนวนมากจะไม่เข้าสู่บริบทของโมเดล:

• search_table: ผลลัพธ์อินทรีย์เป็นตารางที่จัดเรียงและค้นหาได้
• search_dashboard: เมตริกสรุป แผนภูมิการแยกแหล่งที่มา และตารางผลลัพธ์พร้อมแผงรายละเอียดที่คลิกเพื่อขยาย

ทั้งสองยอมรับ params เดียวกับ search โฮสต์ที่ไม่รองรับแอป MCP จะเพิกเฉยต่อเครื่องมือเหล่านี้

ดูตัวอย่างในเครื่องโดยไม่ต้องมีโฮสต์ MCP:

uv run fastmcp dev apps src/server.py

การพัฒนา

# 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"

การแก้ไขปัญหา

• "Missing API key": รวมคีย์ในเส้นทาง URL /{YOUR_KEY}/mcp หรือส่วนหัว Bearer YOUR_KEY
• "Invalid key": ตรวจสอบที่ serpapi.com/dashboard
• "Rate limit exceeded": รอหรืออัปเกรดแผน SerpApi ของคุณ
• "No results": ลองคำค้นหาหรือเครื่องมืออื่น

นโยบายความเป็นส่วนตัว

• ส่ง: เฉพาะพารามิเตอร์ที่โฮสต์ MCP ส่งไปยังการเรียกเครื่องมือ เซิร์ฟเวอร์ไม่เห็นการสนทนาที่เหลือ หรือไฟล์ หน่วยความจำ หรือประวัติบนโฮสต์
• ส่งต่อ: การค้นหาแต่ละครั้งไปที่ serpapi.com พร้อมคีย์ API ของคุณ ผลลัพธ์กลับมาโดยไม่เปลี่ยนแปลง ดู นโยบายความเป็นส่วนตัวของ SerpApi สำหรับวิธีที่ SerpApi จัดการการค้นหาและบัญชี
• เก็บ: mcp.serpapi.com บันทึกเมตริกคำขอ (วิธี รหัสสถานะ ระยะเวลา) และไม่เก็บคำค้นหาหรือผลลัพธ์ คีย์ในเส้นทาง URL อาจปรากฏในบันทึกคำขอ ดังนั้นควรใช้ส่วนหัว
• บันเดิลในเครื่อง: ส่วนขยาย Claude Desktop รันบนเครื่องของคุณ เก็บคีย์ในการตั้งค่าของ Claude Desktop และเรียก serpapi.com โดยตรง ไม่มีอะไรผ่าน mcp.serpapi.com
• ติดต่อ: privacy@serpapi.com หรือเปิด issue

การมีส่วนร่วม

1. Fork ที่เก็บ
2. สร้างสาขาคุณสมบัติของคุณ: git checkout -b feature/amazing-feature
3. ติดตั้ง dependencies: uv install
4. ทำการเปลี่ยนแปลงของคุณ
5. Commit การเปลี่ยนแปลง: git commit -m 'Add amazing feature'
6. Push ไปยังสาขา: git push origin feature/amazing-feature
7. เปิด Pull Request

สัญญาอนุญาต

MIT License - ดูไฟล์ LICENSE สำหรับรายละเอียด