Serper Search and Scrape MCP Server

0.1.2 · active · verified Sun Apr 19

This package provides a TypeScript-based Model Context Protocol (MCP) server that offers web search and webpage scraping capabilities using the Serper API. Currently at version 0.1.2, it is in early development with an assumed infrequent release cadence, typical for community-driven MCP server implementations. Its core function is to allow AI assistants, such as those within Claude Desktop, to perform structured Google searches and extract content from web pages programmatically. Key differentiators include rich search results (organic, knowledge graph, 'people also ask'), advanced search operators, region/language targeting, and comprehensive page scraping with plain text, markdown, JSON-LD, and metadata extraction, all while integrating seamlessly with MCP-compatible AI clients to enhance their real-time data access and tool-use capabilities.

Common errors

```
Error: SERPER_API_KEY environment variable is not set.
```
cause The `SERPER_API_KEY` environment variable, required for authenticating with the Serper API, is missing or incorrectly configured.

fix Ensure `SERPER_API_KEY` is set in your environment (e.g., in a `.env` file or directly in the MCP client configuration) with a valid API key. Example: `SERPER_API_KEY=your_actual_key_here`.
```
TypeError: require() of ES Module ... not supported. Instead change the require to a dynamic import() ...
```
cause This server is a modern TypeScript-based project likely using ESM, but it is being imported or run in a CommonJS context.

fix Ensure your Node.js environment is configured for ESM (e.g., by using `"type": "module"` in your `package.json` or by using `.mjs` file extensions). For running the server, stick to the `npx` command as shown in the quickstart.
```
Node.js version must be >= 18. Current version is 16.x.x.
```
cause The Node.js version running the server is older than the minimum required version (18).

fix Upgrade your Node.js installation to version 18 or newer. Tools like `nvm` (Node Version Manager) can help manage multiple Node.js versions (e.g., `nvm install 18 && nvm use 18`).

Warnings

gotcha This package requires Node.js version 18 or higher to run. Older Node.js versions are not supported and will prevent the server from starting.
Fix: Upgrade your Node.js installation to version 18 or newer (e.g., using `nvm install 18` and `nvm use 18`).
gotcha A `SERPER_API_KEY` environment variable is mandatory for the server to function. Without a valid key, the Serper API calls for search and scraping will fail.
Fix: Obtain a Serper API key and set it as an environment variable (e.g., in a `.env` file or directly in the client configuration) before running the server.
gotcha Debugging MCP servers can be challenging due to stdio-based communication. The project recommends using the Model Context Protocol Inspector tool for effective debugging.
Fix: Run `npm run inspector` in the server's directory to launch the MCP Inspector, which provides a browser-based debugging interface.
breaking As this package is in an early development phase (version 0.1.2), its API and internal structure are subject to frequent, potentially breaking changes without major version bumps.
Fix: Monitor the project's GitHub repository for updates and breaking changes when upgrading, and review the README and changelog for each new release.

Install

npm install serper-search-scrape-mcp-server npm
yarn add serper-search-scrape-mcp-server yarn
pnpm add serper-search-scrape-mcp-server pnpm

Imports

startMcpServer
```
import { startMcpServer } from 'serper-search-scrape-mcp-server';
```
This package is primarily designed as an executable server (`npx serper-search-scrape-mcp-server`), not a library for direct programmatic imports. `startMcpServer` is an inferred potential export for programmatic embedding, though typical usage is via CLI or `npx`.
GoogleSearchTool
```
import { GoogleSearchTool } from 'serper-search-scrape-mcp-server';
```
While the server exposes `google_search` as a tool for AI agents, direct programmatic import of `GoogleSearchTool` (or similar class/function) is an inferred pattern for library-style access, not its primary intended use. The server communicates via stdio.
ScrapeTool
```
import { ScrapeTool } from 'serper-search-scrape-mcp-server';
```
Similar to `GoogleSearchTool`, `ScrapeTool` is an inferred programmatic export for the scraping functionality. The server's main interaction model for users is through its MCP interface via AI clients.

Quickstart

This JSON configuration snippet shows how to integrate the server as an MCP server for AI clients like Claude Desktop, using `npx` and setting the necessary environment variable.

{
  "mcpServers": {
    "serper-search": {
      "command": "npx",
      "args": [
        "-y",
        "serper-search-scrape-mcp-server"
      ],
      "env": {
        "SERPER_API_KEY": "your_api_key_here"
      }
    }
  }
}

view raw JSON →