{"_id":"@deepbrainspace/serper-search-mcp","name":"@deepbrainspace/serper-search-mcp","dist-tags":{"latest":"0.2.1"},"versions":{"0.2.1":{"name":"@deepbrainspace/serper-search-mcp","version":"0.2.1","description":"A Model Context Protocol server for Serper.dev search","type":"module","main":"build/index.js","types":"build/index.d.ts","bin":{"serper-search-mcp":"build/index.js"},"publishConfig":{"access":"public"},"dependencies":{"@google/generative-ai":"^0.17.0","@modelcontextprotocol/sdk":"0.6.0","axios":"^1.7.9","dotenv":"^16.4.7","posthog-node":"^4.10.1","uuid":"^11.1.0"},"devDependencies":{"@types/node":"^20.11.24","@types/uuid":"^10.0.0","typescript":"^5.3.3"},"scripts":{"build":"pnpm tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"","watch":"pnpm tsc --watch","inspector":"pnpm @modelcontextprotocol/inspector build/index.js"},"_id":"@deepbrainspace/serper-search-mcp@0.2.1","_integrity":"sha512-vh4CEm9vtBnRX7hOFcHrReS9M5aCgClemzE7cnA+CUMsr5pnkUa/c++XbmVgzr420N7/GmHxKOBhsPIK1qqUKg==","_resolved":"/tmp/aaf8d7677a41271a79409a0d952a33a5/deepbrainspace-serper-search-mcp-0.2.1.tgz","_from":"file:deepbrainspace-serper-search-mcp-0.2.1.tgz","_nodeVersion":"22.13.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-vh4CEm9vtBnRX7hOFcHrReS9M5aCgClemzE7cnA+CUMsr5pnkUa/c++XbmVgzr420N7/GmHxKOBhsPIK1qqUKg==","shasum":"4b516e8b9f05766ccca52771a2a3cd03b13d8874","tarball":"https://registry.npmjs.org/@deepbrainspace/serper-search-mcp/-/serper-search-mcp-0.2.1.tgz","fileCount":48,"unpackedSize":121129,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDgo9bYT84JQykjGxTAlPwFl36KK7q0si4HkKKDoAYFmwIgIg/ex11uGn/bAYXLkKinn7LE8Rvtjf4uX0MTD/gsjDA="}]},"_npmUser":{"name":"wizardsupreme","email":"smn7818@gmail.com"},"directories":{},"maintainers":[{"name":"wizardsupreme","email":"smn7818@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/serper-search-mcp_0.2.1_1747770880959_0.6733528705584919"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-20T19:54:40.905Z","0.2.1":"2025-05-20T19:54:41.139Z","modified":"2025-05-20T19:54:41.392Z"},"maintainers":[{"name":"wizardsupreme","email":"smn7818@gmail.com"}],"description":"A Model Context Protocol server for Serper.dev search","readme":"# Serper Search MCP Server\n\nA Model Context Protocol server that provides Google search capabilities through the Serper API, along with an AI-powered Deep Research tool. This server enables easy integration of search and research functionality into your MCP-enabled applications.\n\n## ✨ Features\n\n- 🌐 Powerful Google search integration through Serper API\n- 🔄 Rich search response data including:\n  - Knowledge Graph information\n  - Organic search results\n  - \"People Also Ask\" questions\n  - Related searches\n- 🧠 AI-powered Deep Research tool:\n  - Performs multi-step, iterative research\n  - Generates sub-queries to explore topics thoroughly\n  - Synthesizes information from multiple sources\n  - Provides citations for all information\n  - Adjustable research depth levels\n  - Built-in quality metrics for continuous improvement\n- 🛠 Configurable search parameters:\n  - Country targeting\n  - Language selection\n  - Result count customization\n  - Autocorrect options\n- 🔒 Secure API key handling\n- ⚡️ Rate limiting and caching support\n- 📝 TypeScript support with full type definitions\n- 📊 Integrated performance metrics for result optimization\n\n## 🚀 Installation\n\nTo use the Serper Search MCP server, you can run it directly using `npx` or install it globally.\n\n**Using NPX (recommended for quick use):**\nNo installation step is needed. You can run the server directly (see \"Usage with NPX\" section below).\n\n**Global Installation (optional):**\n```bash\npnpm add -g @deepbrain/serper-search-mcp\n```\nOr using npm:\n```bash\nnpm install -g @deepbrain/serper-search-mcp\n```\n\n## ⚙️ Configuration\n\n1. Get your Serper API key from [Serper.dev](https://serper.de\n\n2. Create a `.env` file in the root directory where you run the server (e.g., when using `npx`):\n```env\n# --- Required for basic search ---\nSERPER_API_KEY=your_api_key_here\n\n# --- Optional: LLM Configuration for Deep Research tool ---\n# The Deep Research tool requires an LLM. Configure it using the variables below.\n# If SERPER_LLM_API_KEY is not provided, the Deep Research tool will be unavailable.\n\nSERPER_LLM_PROVIDER=\"google\"  # Or \"openrouter\". Defaults to \"google\".\nSERPER_LLM_API_KEY=\"your_llm_api_key_here\" # Your API key for either Google (Gemini) or OpenRouter.\nSERPER_LLM_MODEL=\"\"           # Optional. Override the default model for the chosen provider.\n                              # Default for Google: \"gemini-2.0-flash-lite-preview-02-05\"\n                              # Default for OpenRouter: \"google/gemini-flash-1.5\" (or other suitable model)\n\n# --- Optional: Advanced Quality Metrics Configuration ---\n# (These are pre-configured by default)\n# USAGE_METRICS_KEY=your-custom-metrics-key\n# USAGE_PROJECT_ID=your-custom-project-id\n# METRICS_ENDPOINT=https://your-custom-host.com\n# DISABLE_METRICS=false # Not recommended\n```\n**LLM Configuration Details:**\n- **`SERPER_LLM_PROVIDER`**: Specifies the LLM provider.\n  - `\"google\"` (default): Uses Google Generative AI (Gemini models). `SERPER_LLM_API_KEY` should be your Google AI Studio API key.\n  - `\"openrouter\"`: Uses OpenRouter. `SERPER_LLM_API_KEY` should be your OpenRouter API key.\n- **`SERPER_LLM_API_KEY`**: The API key for your chosen `SERPER_LLM_PROVIDER`.\n- **`SERPER_LLM_MODEL`**: (Optional) Specify a particular model to use. If not set, a default model for the chosen provider will be used:\n  - Google Default: `gemini-2.0-flash-lite-preview-02-05`\n  - OpenRouter Default: `google/gemini-flash-1.5` (or another suitable model like `mistralai/mistral-7b-instruct`)\n- If `SERPER_LLM_API_KEY` is not provided, the Deep Research tool will be unavailable.\n\nSee [TELEMETRY.md](TELEMETRY.md) for detailed information about:\n- Quality metrics collection\n- Performance monitoring\n- Usage analytics\n- Dashboard setup\n- Continuous improvement\n\n## 🔌 Integration\n\n### Claude Desktop\n\nAdd the server config to your Claude Desktop configuration:\n\n**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"@deepbrain/serper-search-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@deepbrain/serper-search-mcp\" // You can append @version like @0.2.0 if needed\n      ],\n      \"env\": {\n        \"SERPER_API_KEY\": \"your_serper_api_key_here\",\n        // For Deep Research tool (if needed):\n        \"SERPER_LLM_PROVIDER\": \"google\",  // or \"openrouter\"\n        \"SERPER_LLM_API_KEY\": \"your_actual_llm_api_key\",\n        \"SERPER_LLM_MODEL\": \"\" // Optional: \"gemini-2.5-pro-preview-05-06\" or other model\n        // \"DEBUG\": \"true\" // If your server uses this for more verbose logging\n      }\n    }\n  }\n}\n```\nIf you installed it globally (e.g., `pnpm add -g @deepbrain/serper-search-mcp`), you might be able to use a simpler command, ensuring the environment variables are set in the MCP client's `env` block:\n```json\n{\n  \"mcpServers\": {\n    \"@deepbrain/serper-search-mcp\": {\n      \"command\": \"serper-search-mcp\", // This is the binary name from your package.json\n      \"env\": {\n        \"SERPER_API_KEY\": \"your_serper_api_key_here\",\n        \"SERPER_LLM_PROVIDER\": \"google\", // or \"openrouter\"\n        \"SERPER_LLM_API_KEY\": \"your_actual_llm_api_key\"\n        // \"SERPER_LLM_MODEL\": \"your_preferred_model\" // Optional\n      }\n    }\n  }\n}\n```\n\n## 🛠 Usage with NPX\n\nYou can run the server directly from the command line using `npx`:\n\n```bash\nnpx @deepbrain/serper-search-mcp\n```\n\nMake sure you have your `.env` file configured in the directory where you run this command, or set the environment variables (`SERPER_API_KEY`, etc.) in your shell.\n\nIf you have it installed globally, you can run:\n```bash\nserper-search-mcp\n```\n\n### Search Tool\n\n### Search Tool\n\nThe server provides a powerful search tool with the following parameters:\n\n```typescript\n{\n  \"query\": string,          // Search query\n  \"numResults\"?: number,    // Number of results (default: 10, max: 100)\n  \"gl\"?: string,           // Country code (e.g., \"us\", \"uk\")\n  \"hl\"?: string,           // Language code (e.g., \"en\", \"es\")\n  \"autocorrect\"?: boolean, // Enable autocorrect (default: true)\n  \"type\"?: \"search\"        // Search type (more types coming soon)\n}\n```\n\n### Deep Research Tool\n\nFor more comprehensive research needs, the server provides a deep research tool that performs multi-step research with the following parameters:\n\n```typescript\n{\n  \"query\": string,          // Research query or question\n  \"depth\"?: \"basic\" | \"standard\" | \"deep\",  // Research depth (default: \"standard\")\n  \"maxSources\"?: number     // Maximum sources to include (default: 10)\n}\n```\n\nThe deep research tool:\n- Breaks down complex queries into focused sub-queries\n- Executes multiple searches to gather comprehensive information\n- Uses AI to synthesize information from multiple sources\n- Formats results with proper citations and references\n- Adapts its research strategy based on intermediate results\n- Collects anonymous quality metrics to improve search results\n\nDepth Levels:\n- basic: Quick overview (3-5 sources, ~5 min)\n  Good for: Simple facts, quick definitions, straightforward questions\n- standard: Comprehensive analysis (5-10 sources, ~10 min)\n  Good for: Most research needs, balanced depth and speed\n- deep: Exhaustive research (10+ sources, ~15-20 min)\n  Good for: Complex topics, academic research, thorough analysis\n\n### Search Tool Example Response\n\nThe search results include rich data:\n\n```json\n{\n  \"searchParameters\": {\n    \"q\": \"apple inc\",\n    \"gl\": \"us\",\n    \"hl\": \"en\",\n    \"autocorrect\": true,\n    \"type\": \"search\"\n  },\n  \"knowledgeGraph\": {\n    \"title\": \"Apple\",\n    \"type\": \"Technology company\",\n    \"website\": \"http://www.apple.com/\",\n    \"description\": \"Apple Inc. is an American multinational technology company...\",\n    \"attributes\": {\n      \"Headquarters\": \"Cupertino, CA\",\n      \"CEO\": \"Tim Cook (Aug 24, 2011–)\",\n      \"Founded\": \"April 1, 1976, Los Altos, CA\"\n    }\n  },\n  \"organic\": [\n    {\n      \"title\": \"Apple\",\n      \"link\": \"https://www.apple.com/\",\n      \"snippet\": \"Discover the innovative world of Apple...\",\n      \"position\": 1\n    }\n  ],\n  \"peopleAlsoAsk\": [\n    {\n      \"question\": \"What does Apple Inc mean?\",\n      \"snippet\": \"Apple Inc., formerly Apple Computer, Inc....\",\n      \"link\": \"https://www.britannica.com/topic/Apple-Inc\"\n    }\n  ],\n  \"relatedSearches\": [\n    {\n      \"query\": \"Who invented the iPhone\"\n    }\n  ]\n}\n```\n\n## 🔍 Response Types\n\n### Knowledge Graph\nContains entity information when available:\n- Title and type\n- Website URL\n- Description\n- Key attributes\n\n### Organic Results\nList of search results including:\n- Title and URL\n- Snippet (description)\n- Position in results\n- Sitelinks when available\n\n### People Also Ask\nCommon questions related to the search:\n- Question text\n- Answer snippet\n- Source link\n\n### Related Searches\nList of related search queries users often make.\n\n## 📊 Quality Metrics\n\nThe Deep Research tool includes integrated quality metrics:\n\n- Research process metrics\n- Performance monitoring\n- Issue tracking\n- Usage patterns\n- Result quality indicators\n\nSee [TELEMETRY.md](TELEMETRY.md) for detailed information about the metrics collected to improve search quality.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Serper API](https://serper.dev) for providing the Google search capabilities\n- [Model Context Protocol](https://github.com/modelcontextprotocol/mcp) for the MCP framework\n- [PostHog](https://posthog.com) for analytics capabilities\n","readmeFilename":"README.md","_rev":"1-a379c2cb77e4f52f620c8126f8dba24b"}