SerpApi MCP

Server MCP SerpApi

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

Fitur

• Pencarian Multi-Mesin: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay, dan lainnya
• Sumber Daya Mesin: Skema parameter per-mesin tersedia melalui sumber daya MCP (lihat Alat Pencarian)
• 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 hingga 50% rata-rata dan lebih dari 90% untuk API dengan JSON bertingkat yang kompleks.
• UI Interaktif (Aplikasi MCP): Alat search_table dan search_dashboard opsional yang merender hasil sebagai UI interaktif di host yang mendukung
• Ekstensi Claude Desktop: Instalasi lokal satu-klik dari Paket MCP (.mcpb), lihat di bawah

Mulai Cepat

Server MCP SerpApi tersedia sebagai layanan yang dihosting di mcp.serpapi.com. Untuk terhubung ke sana, Anda perlu memberikan kunci API. Anda dapat menemukan kunci API Anda di dasbor SerpApi.

Anda dapat mengonfigurasi Claude Desktop untuk menggunakan server yang dihosting:

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

Anda juga dapat menambahkan server yang dihosting 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

Konfigurasi 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 (Paket MCP)

Untuk instalasi lokal satu-klik, unduh paket .mcpb dari rilis terbaru (atau bangun seperti di bawah) dan buka dengan Claude Desktop (atau seret ke Pengaturan → Ekstensi). Claude Desktop meminta kunci API SerpApi Anda selama instalasi, menyimpannya sebagai pengaturan sensitif, dan menjalankan server secara lokal melalui stdio. Paket ini menggunakan runtime MCPB uv: paket ini hanya mengirimkan sumber, pyproject.toml dan uv.lock, dan Claude Desktop menyediakan Python dan dependensi terkunci dengan uv pada saat instalasi, sehingga tidak ada yang dijual dan satu paket berfungsi di macOS, Windows, dan Linux.

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

Semua yang terkait paket berada di mcpb/, plus .mcpbignore di root proyek. Build meregenerasi skema mesin dari SerpApi Playground (--no-rebuild-engines menggabungkan engines/ dari pohon kerja sebagai gantinya), memvalidasi mcpb/manifest.json, mengemas file yang dilacak git dikurangi .mcpbignore dengan manifes di root paket, lalu menginstalnya ke direktori sementara dan memulainya melalui stdio untuk memastikan berfungsi (--no-smoke melewati langkah terakhir itu). Paket hanya dibuat pada saat rilis: mendorong tag v<version> menjalankan alur kerja rilis, yang menjalankan rangkaian pengujian dan kemudian menyebarkan server yang dihosting, menerbitkan entri Registri MCP, dan membuat paket serta melampirkannya ke rilis GitHub. Permintaan tarik menjalankan pengujian manifes dan titik masuk stdio di tests/test_mcpb.py tetapi tidak mengemas paket.

Titik masuk stdio yang sama berfungsi dengan host MCP lokal mana pun yang meluncurkan 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 tetap di luar URL dan log)
• Berbasis jalur: /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 '...'

Tidak perlu kunci untuk terhubung, membuat daftar alat, atau membaca sumber daya. search dan alat Aplikasi membutuhkannya dan mengembalikan kesalahan tanpanya.

Alat Pencarian

Server MCP memiliki satu Alat 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 diekspos sebagai sumber daya MCP: serpapi://engines (indeks) dan serpapi://engines/<engine>. Klien yang mendukung penyelesaian argumen dapat meminta saran nama mesin untuk serpapi://engines/{engine_name}. Misalnya, awalan google_f menyarankan pengidentifikasi mesin yang cocok. Ini melengkapi parameter URI sumber daya, bukan kueri pencarian arbitrer.

Parameter yang dapat Anda berikan spesifik untuk setiap mesin API. Beberapa contoh parameter disediakan di bawah:

• params.q (wajib): Kueri pencarian
• params.engine: Mesin pencarian (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, sementara Markdown dikembalikan tanpa perubahan
• ...lihat parameter lain 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 - terdeteksi dan diformat secara otomatis.

Respons pencarian mempertahankan string structuredContent.result MCP yang ada dan menyertakan string yang sama dalam konten teks. Untuk output JSON, result berisi JSON berseri; klien yang ada dapat terus menguraikannya dengan JSON.parse(response.structuredContent.result). Untuk output Markdown, ini berisi Markdown yang tidak berubah. Kesalahan dan pembatalan menggunakan pembungkus yang sama. Kegagalan eksekusi pencarian mengatur isError: true; klien yang menggunakan call_tool() tingkat tinggi FastMCP harus menangani ToolError, atau menggunakan call_tool_mcp() untuk memeriksa flag hasil. Lihat hasil alat MCP.

search menggunakan katalog mesin dan aturan khusus mesin untuk mengidentifikasi parameter yang hilang. Klien yang mendukung MCP 2026-07-28 menerima formulir sebelum pencarian apa pun dijalankan. Jawaban yang diterima divalidasi; penolakan atau pembatalan tidak menjalankan pencarian. Klien lama dan klien tanpa pengumpulan formulir menerima kesalahan yang mencantumkan parameter yang hilang sehingga agen dapat bertanya dalam percakapan. Lihat permintaan input MCP.

• Google Flights: pengidentifikasi keberangkatan dan kedatangan, tanggal keberangkatan, dan tanggal kembali untuk perjalanan pulang-pergi. Tanggal dan pengidentifikasi bandara diperiksa. Pencarian berbasis token, rencana perjalanan multi-kota, dan selected_flights_json mempertahankan perilaku yang ada.
• Google Hotels: kueri tujuan atau hotel, tanggal check-in, dan tanggal check-out. Check-out harus mengikuti check-in. Jumlah tamu dan filter opsional lainnya mempertahankan nilai pemanggil atau default API.
• Google Maps Directions: alamat mulai dan tujuan yang hilang. Koordinat atau ID data tempat yang sudah disediakan memenuhi titik akhir yang sesuai.
• Mesin katalog lainnya menggunakan bidang wajibnya, seperti search_query YouTube, find_loc Yelp, dan k Amazon. Aturan mesin memperhitungkan default dan alternatif yang diketahui, termasuk node kategori Amazon, kategori eBay, dan pencarian kutipan Google Scholar.

Formulir diturunkan dari argumen asli pada setiap permintaan. Ini tidak menggunakan requestState atau penyimpanan kelanjutan khusus proses, sehingga percobaan ulang dapat berjalan di replika lain tanpa kunci perlindungan status bersama. Autentikasi diterapkan pada setiap permintaan HTTP, dan hanya jawaban untuk bidang yang diminta yang digunakan. Jika jawaban memperkenalkan persyaratan lain, alat mencantumkan bidang yang tersisa untuk disediakan agen dalam panggilan baru.

Untuk memperluas pencarian terpandu, tambahkan bidang wajib, deskripsi, jenis, dan opsi ke file engines/<engine>.json mesin. Tambahkan entri EngineInputRules di src/engine_input_rules.py saat persyaratan bergantung pada parameter lain, default, atau alternatif. Penangan MCP bersama di src/search_input.py tidak memerlukan cabang khusus mesin. Formulir mendukung string, angka, boolean, dan bidang pilihan tunggal; bidang kompleks yang tidak didukung menerima kesalahan parameter yang hilang. Mesin yang tidak dikenal diteruskan ke SerpApi.

UI Interaktif (Aplikasi MCP)

Alat search mengembalikan JSON secara default. Untuk host yang mendukung ekstensi Aplikasi MCP (SEP-1865), dua alat opsional merender hasil sebagai UI interaktif langsung dalam percakapan, sehingga JSON SERP massal tidak pernah masuk ke konteks model:

• search_table: hasil organik sebagai tabel yang dapat diurutkan dan dicari.
• search_dashboard: metrik ringkasan, bagan rincian sumber, dan tabel hasil dengan panel detail klik-untuk-perluas.

Keduanya menerima params yang sama dengan search. Host yang tidak mendukung Aplikasi MCP hanya mengabaikan alat ini.

Pratinjau secara lokal tanpa host MCP:

uv run fastmcp dev apps src/server.py

Pengembangan

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

Pemecahan Masalah

• "Kunci API hilang": Sertakan kunci di jalur URL /{YOUR_KEY}/mcp atau header Bearer YOUR_KEY
• "Kunci tidak valid": Verifikasi di serpapi.com/dashboard
• "Batas kecepatan terlampaui": Tunggu atau tingkatkan paket SerpApi Anda
• "Tidak ada hasil": Coba kueri atau mesin yang berbeda

Kebijakan Privasi

• Dikirim: hanya parameter yang diteruskan host MCP ke panggilan alat. Server tidak pernah melihat sisa percakapan, atau file, memori, atau riwayat di host.
• Diteruskan: setiap pencarian menuju ke serpapi.com dengan kunci API Anda; hasil kembali tanpa perubahan. Lihat Kebijakan Privasi SerpApi untuk 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 jalur URL dapat muncul di log permintaan, jadi lebih suka header.
• Paket lokal: ekstensi Claude Desktop berjalan di mesin 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 buka masalah.

Berkontribusi

1. Fork repositori
2. Buat cabang fitur Anda: git checkout -b feature/amazing-feature
3. Instal dependensi: uv install
4. Buat perubahan Anda
5. Komit perubahan: git commit -m 'Add amazing feature'
6. Dorong ke cabang: git push origin feature/amazing-feature
7. Buka Permintaan Tarik

Lisensi

Lisensi MIT - lihat file LICENSE untuk detailnya.