SerpApi MCP

SerpApi MCP सर्वर

एक मॉडल कॉन्टेक्स्ट प्रोटोकॉल (MCP) सर्वर कार्यान्वयन जो SerpApi के साथ एकीकृत होता है, व्यापक खोज इंजन परिणाम और डेटा निष्कर्षण के लिए।

विशेषताएँ

• मल्टी-इंजन खोज: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay, और अधिक
• इंजन संसाधन: प्रति-इंजन पैरामीटर स्कीमा MCP संसाधनों के माध्यम से उपलब्ध (खोज टूल देखें)
• रीयल-टाइम मौसम डेटा: खोज क्वेरी के माध्यम से स्थान-आधारित मौसम और पूर्वानुमान
• स्टॉक मार्केट डेटा: खोज एकीकरण के माध्यम से कंपनी वित्तीय और बाजार डेटा
• गतिशील परिणाम प्रसंस्करण: विभिन्न परिणाम प्रकारों को स्वचालित रूप से पहचानता और प्रारूपित करता है
• लचीले प्रतिक्रिया मोड: पूर्ण या संक्षिप्त JSON प्रतिक्रियाएँ
• JSON प्रतिक्रियाएँ (डिफ़ॉल्ट): पूर्ण या संक्षिप्त मोड के साथ संरचित JSON आउटपुट
• मार्कडाउन प्रतिक्रियाएँ: टोकन उपयोग को औसतन 50% और जटिल नेस्टेड JSON वाले APIs के लिए 90% से अधिक कम करें।
• इंटरैक्टिव UI (MCP ऐप्स): ऑप्ट-इन search_table और search_dashboard टूल जो सहायक होस्ट में परिणामों को इंटरैक्टिव UI के रूप में प्रस्तुत करते हैं
• Claude डेस्कटॉप एक्सटेंशन: MCP बंडल (.mcpb) से एक-क्लिक स्थानीय इंस्टॉलेशन, नीचे देखें

त्वरित प्रारंभ

SerpApi MCP सर्वर mcp.serpapi.com पर होस्टेड सेवा के रूप में उपलब्ध है। इसे कनेक्ट करने के लिए, आपको एक API कुंजी प्रदान करनी होगी। आप अपनी API कुंजी अपने SerpApi डैशबोर्ड पर पा सकते हैं।

आप होस्टेड सर्वर का उपयोग करने के लिए Claude डेस्कटॉप कॉन्फ़िगर कर सकते हैं:

{
  "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 डेस्कटॉप कॉन्फ़िगर करें:

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

अपनी API कुंजी प्राप्त करें: serpapi.com/manage-api-key

Claude डेस्कटॉप एक्सटेंशन (MCP बंडल)

स्थानीय, एक-क्लिक इंस्टॉलेशन के लिए, नवीनतम रिलीज़ से .mcpb बंडल डाउनलोड करें (या नीचे दिए अनुसार इसे बनाएं) और इसे Claude डेस्कटॉप के साथ खोलें (या इसे सेटिंग्स → एक्सटेंशन पर खींचें)। Claude डेस्कटॉप इंस्टॉलेशन के दौरान आपकी SerpApi API कुंजी पूछता है, इसे संवेदनशील सेटिंग के रूप में संग्रहीत करता है, और सर्वर को stdio पर स्थानीय रूप से चलाता है। बंडल MCPB uv रनटाइम का उपयोग करता है: यह केवल स्रोत, pyproject.toml और uv.lock भेजता है, और Claude डेस्कटॉप इंस्टॉलेशन समय पर uv के साथ Python और लॉक किए गए निर्भरताएँ प्रदान करता है, इसलिए कुछ भी वेंडर नहीं किया जाता है और एक बंडल macOS, Windows और Linux पर काम करता है।

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

बंडल से संबंधित सब कुछ mcpb/ में रहता है, साथ ही प्रोजेक्ट रूट पर .mcpbignore। बिल्ड SerpApi प्लेग्राउंड से इंजन स्कीमा पुनर्जीवित करता है (--no-rebuild-engines कार्यशील ट्री से engines/ बंडल करता है), mcpb/manifest.json को मान्य करता है, .mcpbignore को छोड़कर git-ट्रैक की गई फ़ाइलों को मैनिफेस्ट के साथ बंडल रूट पर पैक करता है, फिर इसे अस्थायी निर्देशिका में इंस्टॉल करता है और यह सुनिश्चित करने के लिए stdio पर शुरू करता है कि यह काम करता है (--no-smoke अंतिम चरण को छोड़ देता है)। बंडल केवल रिलीज़ समय पर बनाया जाता है: v<version> टैग को पुश करना रिलीज़ वर्कफ़्लो चलाता है, जो परीक्षण सूट चलाता है और फिर होस्टेड सर्वर को तैनात करता है, MCP रजिस्ट्री प्रविष्टि प्रकाशित करता है, और बंडल बनाकर GitHub रिलीज़ से जोड़ता है। पुल अनुरोध tests/test_mcpb.py में मैनिफेस्ट और stdio प्रवेश बिंदु परीक्षण चलाते हैं लेकिन बंडल पैक नहीं करते हैं।

वही 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 इंजन और परिणाम प्रकारों का समर्थन करता है। आप SerpApi API संदर्भ पर सभी उपलब्ध पैरामीटर पा सकते हैं। इंजन पैरामीटर स्कीमा 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" पर सेट करें
• mode: प्रतिक्रिया मोड; "compact" JSON से मेटाडेटा हटाता है, जबकि मार्कडाउन अपरिवर्तित लौटाया जाता है
• ...अन्य पैरामीटर SerpApi API संदर्भ पर देखें

उदाहरण:

{"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 देखें)।

परिणाम प्रकार: उत्तर बॉक्स, जैविक परिणाम, समाचार, चित्र, शॉपिंग - स्वचालित रूप से पहचाने और प्रारूपित किए जाते हैं।

खोज प्रतिक्रियाएँ मौजूदा MCP structuredContent.result स्ट्रिंग को संरक्षित करती हैं और टेक्स्ट सामग्री में समान स्ट्रिंग शामिल करती हैं। JSON आउटपुट के लिए, result में क्रमबद्ध JSON होता है; मौजूदा क्लाइंट JSON.parse(response.structuredContent.result) के साथ इसे पार्स करना जारी रख सकते हैं। मार्कडाउन आउटपुट के लिए, इसमें अपरिवर्तित मार्कडाउन होता है। त्रुटियाँ और रद्दीकरण समान रैपर का उपयोग करते हैं। खोज निष्पादन विफलताएँ isError: true सेट करती हैं; FastMCP के उच्च-स्तरीय call_tool() का उपयोग करने वाले क्लाइंट को ToolError को संभालना चाहिए, या परिणाम फ़्लैग का निरीक्षण करने के लिए call_tool_mcp() का उपयोग करना चाहिए। MCP टूल परिणाम देखें।

search लापता पैरामीटर की पहचान करने के लिए इंजन कैटलॉग और इंजन-विशिष्ट नियमों का उपयोग करता है। MCP 2026-07-28 का समर्थन करने वाले क्लाइंट को कोई भी खोज चलाने से पहले एक फॉर्म प्राप्त होता है। स्वीकृत उत्तर मान्य किए जाते हैं; अस्वीकार या रद्दीकरण कोई खोज नहीं चलाता। लीगेसी क्लाइंट और फॉर्म निकासी के बिना क्लाइंट को लापता पैरामीटर सूचीबद्ध करने वाली त्रुटि प्राप्त होती है ताकि एजेंट बातचीत में पूछ सके। MCP इनपुट अनुरोध देखें।

• Google Flights: प्रस्थान और आगमन पहचानकर्ता, प्रस्थान तिथि, और राउंड ट्रिप के लिए वापसी तिथि। तिथियाँ और हवाई अड्डे के पहचानकर्ता जाँचे जाते हैं। टोकन-आधारित खोज, मल्टी-सिटी यात्रा कार्यक्रम, और selected_flights_json अपने मौजूदा व्यवहार को बनाए रखते हैं।
• Google Hotels: गंतव्य या होटल क्वेरी, चेक-इन तिथि, और चेक-आउट तिथि। चेक-आउट चेक-इन के बाद होना चाहिए। अतिथि गणना और अन्य वैकल्पिक फ़िल्टर कॉलर के मान या API डिफ़ॉल्ट रखते हैं।
• Google Maps दिशाएँ: लापता प्रारंभ और गंतव्य पते। पहले से आपूर्ति किए गए निर्देशांक या स्थान डेटा ID संबंधित एंडपॉइंट को संतुष्ट करते हैं।
• अन्य कैटलॉग इंजन अपने आवश्यक फ़ील्ड का उपयोग करते हैं, जैसे YouTube का search_query, Yelp का find_loc, और Amazon का k। इंजन नियम ज्ञात डिफ़ॉल्ट और विकल्पों के लिए जिम्मेदार हैं, जिनमें Amazon श्रेणी नोड, eBay श्रेणियाँ, और Google Scholar उद्धरण खोज शामिल हैं।

फॉर्म प्रत्येक अनुरोध पर मूल तर्कों से प्राप्त होता है। यह कोई requestState या प्रक्रिया-स्थानीय निरंतरता भंडारण का उपयोग नहीं करता है, इसलिए एक पुनः प्रयास साझा राज्य-सुरक्षा कुंजी के बिना दूसरे प्रतिकृति पर चल सकता है। प्रमाणीकरण प्रत्येक HTTP अनुरोध पर लागू होता है, और केवल अनुरोधित फ़ील्ड के उत्तर उपयोग किए जाते हैं। यदि कोई उत्तर दूसरी आवश्यकता पेश करता है, तो टूल एजेंट को नए कॉल में आपूर्ति करने के लिए शेष फ़ील्ड सूचीबद्ध करता है।

निर्देशित खोज का विस्तार करने के लिए, इंजन की engines/<engine>.json फ़ाइल में आवश्यक फ़ील्ड, विवरण, प्रकार और विकल्प जोड़ें। src/engine_input_rules.py में EngineInputRules प्रविष्टि जोड़ें जब आवश्यकताएँ अन्य पैरामीटर, डिफ़ॉल्ट या विकल्पों पर निर्भर करती हैं। src/search_input.py में साझा MCP हैंडलर को इंजन-विशिष्ट शाखाओं की आवश्यकता नहीं है। फॉर्म स्ट्रिंग, संख्याएँ, बूलियन और एकल-विकल्प फ़ील्ड का समर्थन करते हैं; असमर्थित जटिल फ़ील्ड लापता-पैरामीटर त्रुटि प्राप्त करते हैं। अज्ञात इंजन SerpApi को पास होते हैं।

इंटरैक्टिव UI (MCP ऐप्स)

search टूल डिफ़ॉल्ट रूप से JSON लौटाता है। MCP ऐप्स एक्सटेंशन (SEP-1865) का समर्थन करने वाले होस्ट के लिए, दो ऑप्ट-इन टूल परिणामों को सीधे बातचीत में इंटरैक्टिव UI के रूप में प्रस्तुत करते हैं, इसलिए बड़ा SERP JSON मॉडल के संदर्भ विंडो में कभी प्रवेश नहीं करता:

• search_table: जैविक परिणाम एक क्रमबद्ध, खोजने योग्य तालिका के रूप में।
• search_dashboard: सारांश मेट्रिक्स, एक स्रोत-विभाजन चार्ट, और क्लिक-टू-विस्तार विवरण पैनल के साथ एक परिणाम तालिका।

दोनों search के समान params स्वीकार करते हैं। 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"

समस्या निवारण

• "लापता API कुंजी": URL पथ /{YOUR_KEY}/mcp या हेडर Bearer YOUR_KEY में कुंजी शामिल करें
• "अमान्य कुंजी": serpapi.com/dashboard पर सत्यापित करें
• "दर सीमा पार हो गई": प्रतीक्षा करें या अपनी SerpApi योजना को अपग्रेड करें
• "कोई परिणाम नहीं": विभिन्न क्वेरी या इंजन आज़माएँ

गोपनीयता नीति

• भेजा गया: केवल वे पैरामीटर जो MCP होस्ट टूल कॉल में पास करता है। सर्वर बातचीत के बाकी हिस्से, या होस्ट पर फ़ाइलें, मेमोरी या इतिहास कभी नहीं देखता।
• अग्रेषित: प्रत्येक खोज आपकी API कुंजी के साथ serpapi.com पर जाती है; परिणाम अपरिवर्तित लौटते हैं। SerpApi खोजों और खातों को कैसे संभालता है, इसके लिए SerpApi गोपनीयता नीति देखें।
• रखा गया: mcp.serpapi.com अनुरोध मेट्रिक्स (विधि, स्थिति कोड, अवधि) रिकॉर्ड करता है और कोई क्वेरी या परिणाम संग्रहीत नहीं करता। URL पथ में एक कुंजी अनुरोध लॉग में दिखाई दे सकती है, इसलिए हेडर को प्राथमिकता दें।
• स्थानीय बंडल: Claude डेस्कटॉप एक्सटेंशन आपकी मशीन पर चलता है, कुंजी को Claude डेस्कटॉप की सेटिंग्स में रखता है और सीधे serpapi.com को कॉल करता है। कुछ भी mcp.serpapi.com से नहीं गुजरता।
• संपर्क: privacy@serpapi.com, या एक मुद्दा खोलें।

योगदान

1. रिपॉजिटरी को फोर्क करें
2. अपनी फीचर शाखा बनाएं: git checkout -b feature/amazing-feature
3. निर्भरताएँ स्थापित करें: uv install
4. अपने परिवर्तन करें
5. परिवर्तन कमिट करें: git commit -m 'Add amazing feature'
6. शाखा पर पुश करें: git push origin feature/amazing-feature
7. एक पुल अनुरोध खोलें

लाइसेंस

MIT लाइसेंस - विवरण के लिए LICENSE फ़ाइल देखें।