Serper Web Inquiry and Content Acquisition MCP Endpoint

This is a TypeScript implementation of an MCP server leveraging the Serper API to execute web searches and extract textual data from remote URLs. It is designed for seamless integration with environments like Claude Desktop to inject real-time web intelligence.

Core Capabilities

Available Operations

google_search - Execute internet lookups through the Serper gateway
Yields comprehensive results: standard organic listings, knowledge panel data, 'frequently asked questions,' and related query suggestions.
Permits granular control over geographical location and linguistic settings.
Accepts supplementary configurations for result offset, result depth, temporal constraints, and query normalization.
Supports advanced directive filtering:
- site: Constrain results to a specific domain name.
- filetype: Restrict output to specific file formats (e.g., 'pdf', 'txt').
- inurl: Target pages containing specified keywords within their address structure.
- intitle: Target pages where the title text matches the criteria.
- related: Identify analogous online destinations.
- cache: Access the last known cached snapshot of a specified address.
- before: Set a cutoff date (format: YYYY-MM-DD).
- after: Set a starting date (format: YYYY-MM-DD).
- exact: Enforce literal phrase matching.
- exclude: Specify terms to omit from the results set.
- or: Define alternative search criteria (logical OR operation).
scrape - Pull content from specified web documents
Outputs raw textual content and optionally formatted Markdown.
Captures embedded structured data (JSON-LD) and <head> element metadata.
Aims to retain the original document's logical organization.

Prerequisites

Runtime environment: Node.js version 18 or newer.
Authorization Token: A valid Serper API credential must be present in the SERPER_API_KEY environmental variable.

Development Lifecycle

Dependency resolution: bash npm install

Compiling the server assets: bash npm run build

For continuous development with auto-recompilation hooks: bash npm run watch

Verification procedures: bash npm test # Execute all unit and integration verification routines npm run test:watch # Run tests interactively with file change monitoring npm run test:coverage # Gauge test effectiveness via coverage reports npm run test:integration # Execute tests targeting external system interactions

Environmental Configuration

Populate a .env file in the root directory:

SERPER_API_KEY=your_actual_api_key_here

Diagnostic Procedures

Troubleshooting MCP server communication over stdio can be difficult. We advise utilizing the MCP Inspector, accessible via a dedicated package script:

bash npm run inspector

The Inspector utility will generate a local URL to facilitate browser-based diagnostic visualization.

Deployment Instructions

Installation via Smithery

Automated setup for Claude Desktop using the Smithery registry:

bash npx -y @smithery/cli install @marcopesani/mcp-server-serper --client claude

Configuration for Claude Desktop

Integrate the server definition into the client's configuration file: - MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%/Claude/claude_desktop_config.json

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

Configuration for Cline

Access the Cline extension preferences panel.
Navigate to the "MCP Servers" section.
Select "Configure MCP Servers".
Insert the following definition:

{ "mcpServers": { "github.com/marcopesani/mcp-server-serper": { "command": "npx", "args": ["-y", "serper-search-scrape-mcp-server"], "env": { "SERPER_API_KEY": "your_api_key_here" }, "disabled": false, "autoApprove": ["google_search", "scrape"] } } }

Supplemental Cline settings: - disabled: A boolean flag; setting to false activates the server. - autoApprove: An array listing the specific functionalities requiring no subsequent usage consent.

Configuration for Cursor

Open Cursor application settings.
Locate and open "Features" settings.
Within the "MCP Servers" grouping, select "Add new MCP Server".
Assign a unique identifier and set the execution "Type" to "command".
Input the command string as follows:

env SERPER_API_KEY=your_api_key_here npx -y serper-search-scrape-mcp-server

Containerized Deployment (Docker)

First, construct the necessary container image:

bash docker build -t mcp-server-serper .

Next, instantiate the container, providing your Serper authentication credential:

bash docker run -e SERPER_API_KEY=your_api_key_here mcp-server-serper

Alternatively, if your configuration variables reside in a local .env file:

bash docker run --env-file .env mcp-server-serper

For active development where source code modification needs immediate reflection, utilize volume mapping:

bash docker run -v $(pwd):/app --env-file .env mcp-server-serper

Crucial Note: Ensure that your_api_key_here is substituted with your genuine Serper credential across all examples.

mcp-server-web-retrieval-serper

Author

tahaswx

Quick Info

Actions

Tags