Serper Web Data Fetching & Parsing Utility (MCP)

A server implementation, written in TypeScript, that furnishes capabilities for performing general web searches and extracting text/metadata from specified URLs using the robust Serper API integration. This utility is designed to work seamlessly with Claude Desktop environments for advanced information gathering.

Core Functionality

Exposed Methods (Tools)

• google_search - Executes indexed web queries through the Serper gateway
• Returns comprehensive result sets: standard listings, knowledge panels, 'People Also Ask' snippets, and associated queries.
• Supports geographical targeting and localization settings.
• Configurable options for result depth (pagination), temporal constraints, and query refinement.

• Advanced query syntax support:

  • site: Restrict results to a specific domain entity
  • filetype: Filter by document format (e.g., 'pdf', 'csv')
  • inurl: Target pages containing specified text within their uniform resource locator
  • intitle: Search for pages where the title matches specified content
  • related: Discover websites structurally similar to a given URL
  • cache: Access the archived snapshot of a designated URL from Google's index
  • before/after: Date-based constraint filtering (YYYY-MM-DD format)
  • exact: Force literal phrase matching
  • exclude: Specify terms to omit from consideration
  • or: Utilize boolean OR logic between search terms

• scrape - Fetches and parses the content body of a designated URI

• Outputs raw text content and optionally output formatted using Markdown syntax.
• Includes extraction of structured data like JSON-LD schema and header meta-tags.
• Attempts to retain the logical document hierarchy during parsing.

Prerequisites

• Runtime environment must be Node.js version 18 or higher.
• A valid API credential for Serper must be configured via the SERPER_API_KEY environment variable.

Local Setup & Building

Install necessary dependencies:

npm install

Compile the source code:

npm run build

For iterative development with automatic recompilation:

npm run watch

Execute automated verification routines:

npm test                  # Full test suite execution
npm run test:watch       # Continuous testing upon file changes
npm run test:coverage    # Run tests and generate coverage reports
npm run test:integration # Execute end-to-end integration checks

Environment Configuration

Establish a .env file in the root folder:

SERPER_API_KEY=your_api_key_here

Diagnostic Assistance

Debugging communication over stdio channels can be complex. We advise leveraging the official MCP Inspector, accessible via a dedicated script:

npm run inspector

The Inspector will launch a local interface accessible via a provided URL in your browser.

Deployment Instructions

Installation via Smithery

Facilitate automatic integration into Claude Desktop using the Smithery CLI:

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

Configuration for Claude Desktop

Modify the client configuration file located at: - MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%/Claude/claude_desktop_config.json

Inject the following structure into the mcpServers map:

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

Cline Utility Integration

1. Navigate to Cline extension settings.
2. Select the "MCP Servers" tab.
3. Choose "Configure MCP Servers".
4. Input the server mapping:

{
  "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"]
    }
  }
}

Additional Cline directives: - disabled: Setting this to false activates the service. - autoApprove: A list of tools permitted for execution without sequential user consent.

Cursor IDE Setup

1. Access Cursor application settings.
2. Navigate to the "Features" configuration pane.
3. Locate the "MCP Servers" section and select "Add new MCP Server".
4. Assign a name and set the configuration "Type" to "command".
5. Populate the "Command" field with:

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

Containerization (Docker)

Build the required Docker image first:

docker build -t mcp-server-serper .

Run the container, supplying the necessary API key environment variable:

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

If utilizing a local .env file for configuration:

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

For development workflows requiring source code access within the container:

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

Crucial Reminder: Substitute placeholder values (e.g., your_api_key_here) with your genuine Serper API credential.