SerpApi MCP

SerpApi MCP Server

Implementasi server Model Context Protocol (MCP) yang terintegrasi dengan SerpApi untuk hasil mesin pencari dan ekstraksi data yang komprehensif.

Fitur

• Pencarian Multi-Mesin: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay, dan lainnya
• Resource Mesin: Skema parameter per mesin tersedia melalui resource MCP (lihat Search Tool)
• Data Cuaca Real-Time: Cuaca berbasis lokasi dengan prakiraan melalui kueri pencarian
• Data Pasar Saham: Data keuangan perusahaan dan pasar melalui integrasi pencarian
• Pemrosesan Hasil Dinamis: Mendeteksi dan memformat berbagai jenis hasil secara otomatis
• Mode Respons Fleksibel: Respons JSON lengkap atau ringkas
• Respons JSON (default): Output JSON terstruktur dengan mode lengkap atau ringkas
• Respons Markdown: Mengurangi penggunaan token rata-rata sebesar 50% dan lebih dari 90% untuk API dengan JSON bertingkat yang kompleks.
• UI Interaktif (MCP Apps): Tool search_table dan search_dashboard yang bersifat opsional dan menampilkan hasil sebagai UI interaktif di host yang mendukungnya
• Ekstensi Claude Desktop: Instalasi lokal sekali klik dari MCP Bundle (.mcpb), lihat di bawah

Mulai cepat

SerpApi MCP Server tersedia sebagai layanan ter-host di mcp.serpapi.com. Untuk terhubung, Anda perlu memberikan kunci API. Anda dapat menemukan kunci API di dasbor SerpApi.

Anda dapat mengonfigurasi Claude Desktop untuk menggunakan server ter-host:

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

Anda juga dapat menambahkan server ter-host ke klien MCP berikut:

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 (membaca kunci dari SERPAPI_API_KEY di shell Anda)

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

Hosting mandiri

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

Konfigurasikan Claude Desktop:

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

Dapatkan kunci API Anda: serpapi.com/manage-api-key

Ekstensi Claude Desktop (MCP bundle)

Untuk instalasi lokal sekali klik, unduh bundle .mcpb dari rilis terbaru dan buka dengan Claude Desktop (atau seret ke Settings → Extensions). Claude Desktop akan meminta kunci API SerpApi Anda selama instalasi, menyimpannya sebagai pengaturan sensitif, dan menjalankan server secara lokal melalui stdio. Python dan dependensi akan disediakan dengan uv saat instalasi. Bundle yang sama dapat digunakan di macOS, Windows, dan Linux.

Titik masuk stdio yang sama dapat digunakan dengan host MCP lokal apa pun yang menjalankan server sebagai subproses:

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

Autentikasi

Dua metode didukung:

• Berbasis header: Authorization: Bearer YOUR_API_KEY (disarankan: kunci tidak muncul di URL dan log)
• Berbasis path: /YOUR_API_KEY/mcp, untuk klien yang tidak dapat mengatur header

Contoh:

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

Kunci tidak diperlukan untuk terhubung, mencantumkan tool, atau membaca resource. search dan tool App memerlukannya dan akan mengembalikan error jika kunci tidak tersedia.

Tool pencarian

Server MCP memiliki satu tool pencarian utama yang mendukung semua mesin dan jenis hasil SerpApi. Anda dapat menemukan semua parameter yang tersedia di referensi API SerpApi. Skema parameter mesin juga tersedia sebagai resource MCP: serpapi://engines (indeks) dan serpapi://engines/<engine>. Klien yang mendukung pelengkapan argumen dapat meminta saran nama mesin untuk serpapi://engines/{engine_name}. Misalnya, awalan google_f menyarankan pengenal mesin yang cocok. Fitur ini melengkapi parameter URI resource, bukan kueri pencarian sembarang.

Parameter yang dapat Anda berikan berbeda-beda untuk setiap mesin API. Beberapa contoh parameter tersedia di bawah:

• params.q (wajib): Kueri pencarian
• params.engine: Mesin pencari (default: "google_light")
• params.location: Filter geografis
• params.output: Format respons; hilangkan untuk JSON (default), atau atur ke "md" untuk Markdown
• mode: Mode respons; "compact" menghapus metadata dari JSON, sedangkan Markdown dikembalikan tanpa perubahan
• ...lihat parameter lainnya di referensi API SerpApi

Contoh:

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

Mesin yang didukung: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay, dan lainnya (lihat serpapi://engines).

Jenis hasil: Kotak jawaban, hasil organik, berita, gambar, belanja — dideteksi dan diformat secara otomatis.

Respons pencarian mempertahankan string MCP structuredContent.result yang sudah ada dan menyertakan string yang sama dalam konten teks. Untuk output JSON, result berisi JSON berserialisasi; klien yang sudah ada dapat terus menguraikannya dengan JSON.parse(response.structuredContent.result). Untuk output Markdown, isinya adalah Markdown yang tidak berubah. Error dan pembatalan menggunakan pembungkus yang sama. Kegagalan eksekusi pencarian menetapkan isError: true; klien yang menggunakan call_tool() tingkat tinggi dari FastMCP harus menangani ToolError, atau menggunakan call_tool_mcp() untuk memeriksa penanda hasil. Lihat hasil tool MCP.

search menggunakan katalog mesin dan aturan khusus mesin untuk mengidentifikasi parameter yang belum diisi. Klien yang mendukung MCP 2026-07-28 akan menerima formulir sebelum pencarian dijalankan. Jawaban yang diterima akan divalidasi; penolakan atau pembatalan tidak akan menjalankan pencarian. Klien lama dan klien tanpa elisitasi formulir akan menerima error yang mencantumkan parameter yang belum diisi agar agen dapat menanyakannya dalam percakapan. Lihat permintaan input MCP.

• Google Flights: pengenal keberangkatan dan kedatangan, tanggal keberangkatan, serta tanggal pulang untuk perjalanan pulang-pergi. Tanggal dan pengenal bandara akan diperiksa. Pencarian berbasis token, rencana perjalanan multi-kota, dan selected_flights_json tetap berperilaku seperti sebelumnya.
• Google Hotels: tujuan atau kueri hotel, tanggal check-in, dan tanggal check-out. Check-out harus setelah check-in. Jumlah tamu dan filter opsional lainnya menggunakan nilai dari pemanggil atau default API.
• Google Maps Directions: alamat awal dan tujuan yang belum diisi. Koordinat atau ID data tempat yang sudah diberikan akan memenuhi kebutuhan untuk titik akhir terkait.
• Mesin katalog lainnya menggunakan kolom wajibnya, seperti search_query milik YouTube, find_loc milik Yelp, dan k milik Amazon. Aturan mesin memperhitungkan default dan alternatif yang diketahui, termasuk node kategori Amazon, kategori eBay, dan pencarian sitasi Google Scholar.

Jika suatu jawaban menambahkan persyaratan lain, tool akan mencantumkan kolom yang masih perlu diisi oleh agen dalam panggilan baru. Formulir mendukung kolom string, angka, boolean, dan pilihan tunggal; kolom kompleks yang tidak didukung akan menghasilkan error parameter yang belum diisi. Mesin yang tidak dikenal akan diteruskan ke SerpApi.

Tool ekstraksi

Tool extract membaca halaman web dan mengembalikan kontennya sebagai JSON atau Markdown terstruktur. Anda dapat mengekstrak satu halaman, menemukan URL situs web, atau merayapi beberapa halaman. Temukan semua parameter yang tersedia di referensi API Extract atau di resource serpapi://engines/extract.

Beberapa parameter yang dapat Anda berikan:

• params.url (wajib): URL halaman atau situs web
• params.mode: Mode ekstraksi; "scrape" (default) membaca satu halaman, "map" menemukan URL, dan "crawl" mengekstrak beberapa halaman
• params.include_markdown: Sertakan konten halaman sebagai Markdown; default-nya true untuk scrape dan crawl, atau atur ke false untuk menonaktifkannya
• params.output: Format respons; default-nya "json" dalam mode lengkap dan "md" dalam mode ringkas. Atur secara eksplisit untuk mengganti format.
• params.max_pages: Jumlah maksimum halaman yang dirayapi, termasuk halaman awal (default: 10, maksimum: 100)
• params.json_restrictor: Pilih kolom yang akan dikembalikan, seperti "markdown,error"
• mode: Mode respons; "complete" (default) mengembalikan respons lengkap. "compact" menggunakan Markdown native secara default. Dengan params.output="json" yang ditentukan secara eksplisit, ekstraksi ringkas satu halaman mempertahankan kolom tingkat teratas markdown jika tersedia dan tetap menyertakan error API. Respons tanpa Markdown, termasuk hasil yang dialihkan ke mesin lain, tetap menyertakan datanya dengan metadata dihapus. Nilai params.json_restrictor yang ditentukan secara eksplisit dan params.include_markdown=false lebih diutamakan saat menggunakan JSON. Untuk map dan crawl, JSON ringkas menghapus metadata. Output Markdown dikembalikan tanpa perubahan.

Contoh:

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

Untuk mendapatkan konten satu halaman dalam Markdown native, gunakan mode="compact". Tambahkan params.output="json" untuk menerima JSON yang berisi kolom markdown. JSON lengkap menyertakan kolom tersebut secara default; JSON crawl menyertakannya di setiap entri pages. Mengatur params.output="json" dan params.include_markdown=false akan mempertahankan kolom terstruktur lainnya tanpa Markdown.

Crawl menggunakan satu kredit pencarian untuk setiap halaman yang berhasil diekstrak pada permintaan yang tidak menggunakan cache. Gunakan params.max_pages untuk membatasi jumlah halaman yang diekstrak.

UI Interaktif (MCP apps)

Tool search mengembalikan JSON secara default. Untuk host yang mendukung ekstensi MCP Apps (SEP-1865), dua tool opsional menampilkan hasil sebagai UI interaktif langsung dalam percakapan, sehingga JSON SERP dalam jumlah besar tidak masuk ke jendela konteks model:

• search_table: hasil organik sebagai tabel yang dapat diurutkan dan ditelusuri.
• search_dashboard: metrik ringkasan, diagram perincian sumber, dan tabel hasil dengan panel detail yang dapat dibuka dengan mengeklik.

Keduanya menerima params yang sama dengan search. Host yang tidak mendukung MCP Apps akan mengabaikan tool ini.

Pemecahan masalah

• "Missing API key": Sertakan kunci di path URL /{YOUR_KEY}/mcp atau header Bearer YOUR_KEY
• "Invalid key": Verifikasi di serpapi.com/dashboard
• "Rate limit exceeded": Tunggu atau tingkatkan paket SerpApi Anda
• "No results": Coba kueri atau mesin lain

Kebijakan privasi

• Dikirim: hanya parameter yang diteruskan host MCP ke pemanggilan tool. Server tidak pernah melihat bagian percakapan lainnya, atau file, memori, maupun riwayat di host.
• Diteruskan: setiap pencarian dikirim ke serpapi.com dengan kunci API Anda; hasil dikembalikan tanpa perubahan. Lihat Kebijakan Privasi SerpApi untuk mengetahui cara SerpApi menangani pencarian dan akun.
• Disimpan: mcp.serpapi.com mencatat metrik permintaan (metode, kode status, durasi) dan tidak menyimpan kueri atau hasil. Kunci di path URL dapat muncul di log permintaan, jadi sebaiknya gunakan header.
• Bundle lokal: ekstensi Claude Desktop berjalan di komputer Anda, menyimpan kunci di pengaturan Claude Desktop, dan memanggil serpapi.com secara langsung. Tidak ada yang melewati mcp.serpapi.com.
• Kontak: privacy@serpapi.com, atau buat issue.

Kontribusi

Lihat CONTRIBUTING.md untuk penyiapan pengembangan, perintah penyegaran skema, pengujian, pembuatan Docker dan MCP Bundle, serta rilis.

Lisensi

Lisensi MIT — lihat file LICENSE untuk detailnya.