Web Search MCP Server - API Documentation

July 29, 2025 ยท View on GitHub

Overview

The Web Search MCP Server provides three tools for web searching and content extraction:

  1. full-web-search - Comprehensive web search with full content extraction (primary tool)
  2. get-web-search-summaries - Lightweight search returning only result snippets
  3. get-single-web-page-content - Extract content from a single web page URL

Description

Search the web and fetch complete page content from top results. This is the most comprehensive web search tool. It searches the web and then follows the resulting links to extract their full page content, providing the most detailed and complete information available.

Input Schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query to execute (recommended for comprehensive research)"
    },
    "limit": {
      "type": "number",
      "description": "Number of results to return with full content (1-10, default 5)",
      "minimum": 1,
      "maximum": 10,
      "default": 5
    },
    "includeContent": {
      "type": "boolean",
      "description": "Whether to fetch full page content (default: true)",
      "default": true
    },
    "maxContentLength": {
      "type": "number",
      "description": "Maximum characters per result content (0 = no limit). Usually not needed - content length is automatically optimized.",
      "optional": true
    }
  },
  "required": ["query"]
}

Output Schema

Returns formatted text content containing search results with full page content:

{
  "content": [
    {
      "type": "text",
      "text": "Search completed for \"[query]\" with [N] results:\n\n**1. [Title]**\nURL: [url]\nDescription: [description]\n\n**Full Content:**\n[extracted content]\n\n---\n\n..."
    }
  ]
}

Usage Examples

{
  "name": "full-web-search",
  "arguments": {
    "query": "TypeScript MCP server"
  }
}

Search with Custom Parameters

{
  "name": "full-web-search",
  "arguments": {
    "query": "web development best practices",
    "limit": 8,
    "includeContent": true,
    "maxContentLength": 3000
  }
}

Tool: get-web-search-summaries

Description

Search the web and return only the search result snippets/descriptions without following links to extract full page content. This is a lightweight alternative to full-web-search for when you only need brief search results.

Input Schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query to execute (lightweight alternative)"
    },
    "limit": {
      "type": "number",
      "description": "Number of search results to return (1-10, default 5)",
      "minimum": 1,
      "maximum": 10,
      "default": 5
    }
  },
  "required": ["query"]
}

Output Schema

Returns formatted text content containing search result summaries:

{
  "content": [
    {
      "type": "text",
      "text": "Search summaries for \"[query]\" with [N] results:\n\n**1. [Title]**\nURL: [url]\nDescription: [description]\n\n---\n\n..."
    }
  ]
}

Usage Examples

{
  "name": "get-web-search-summaries",
  "arguments": {
    "query": "machine learning tutorials"
  }
}

Summary Search with Custom Limit

{
  "name": "get-web-search-summaries",
  "arguments": {
    "query": "React best practices",
    "limit": 3
  }
}

Tool: get-single-web-page-content

Description

Extract and return the full content from a single web page URL. This tool follows a provided URL and extracts the main page content. Useful for getting detailed content from a specific webpage without performing a search.

Input Schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "The URL of the web page to extract content from"
    },
    "maxContentLength": {
      "type": "number",
      "description": "Maximum characters for the extracted content (0 = no limit, undefined = use default limit). Usually not needed - content length is automatically optimized.",
      "optional": true
    }
  },
  "required": ["url"]
}

Output Schema

Returns formatted text content from the specified web page:

{
  "content": [
    {
      "type": "text",
      "text": "**Page Content from: [url]**\n\n**Title:** [title]\n**Word Count:** [count]\n**Content Length:** [length] characters\n\n**Content:**\n[extracted content]"
    }
  ]
}

Usage Examples

Basic Page Content Extraction

{
  "name": "get-single-web-page-content",
  "arguments": {
    "url": "https://example.com/article"
  }
}

Page Content with Length Limit

{
  "name": "get-single-web-page-content",
  "arguments": {
    "url": "https://example.com/long-article",
    "maxContentLength": 2000
  }
}

Response Examples

full-web-search Response

{
  "content": [
    {
      "type": "text",
      "text": "Search completed for \"TypeScript MCP server\" with 2 results:\n\n**1. Getting Started with TypeScript**\nURL: https://www.typescriptlang.org/docs/\nDescription: TypeScript is a strongly typed programming language that builds on JavaScript...\n\n**Full Content:**\nTypeScript is a strongly typed programming language that builds on JavaScript, giving you better tooling at any scale. This tutorial will help you get started with TypeScript...\n\n---\n\n**2. Model Context Protocol Documentation**\nURL: https://modelcontextprotocol.io/\nDescription: The Model Context Protocol (MCP) is a protocol for AI assistants to connect to external data sources...\n\n**Full Content:**\nThe Model Context Protocol (MCP) enables AI assistants to connect to external data sources and tools...\n\n---\n"
    }
  ]
}

get-web-search-summaries Response

{
  "content": [
    {
      "type": "text",
      "text": "Search summaries for \"machine learning tutorials\" with 3 results:\n\n**1. Machine Learning Crash Course**\nURL: https://developers.google.com/machine-learning/crash-course\nDescription: Google's fast-paced, practical introduction to machine learning...\n\n---\n\n**2. Introduction to Machine Learning**\nURL: https://www.coursera.org/learn/machine-learning\nDescription: Learn about the most effective machine learning techniques...\n\n---\n"
    }
  ]
}

get-single-web-page-content Response

{
  "content": [
    {
      "type": "text",
      "text": "**Page Content from: https://example.com/article**\n\n**Title:** example.com/article\n**Word Count:** 1250\n**Content Length:** 8500 characters\n\n**Content:**\nThis is the extracted content from the web page...\n[full page content continues]"
    }
  ]
}

Error Handling

Common Error Types

  1. Network Errors

    • Timeout errors
    • Connection refused
    • DNS resolution failures

  2. Search Errors

    • Invalid search queries
    • Rate limiting by Google
    • CAPTCHA challenges

  3. Content Extraction Errors

    • Page access denied (403, 404)
    • Content encoding issues
    • Malformed HTML

Error Response Format

{
  "error": {
    "message": "Error description",
    "type": "error_type",
    "details": "Additional error information"
  }
}

Rate Limiting

The server implements rate limiting to respect Google's terms of service:

  • Maximum 10 requests per minute
  • Maximum 5 concurrent content extractions
  • Automatic retry with exponential backoff

Performance Considerations

Response Times

  • Search execution: 1-5 seconds
  • Content extraction: 2-10 seconds per URL
  • Total response time: 3-15 seconds (depending on result count)

Content Limits

  • Maximum content length: 50KB per page
  • Maximum concurrent requests: 5
  • Request timeout: 10 seconds

Integration Examples

LM Studio Configuration

{
  "mcpServers": {
    "web-search": {
      "command": "web-search-mcp",
      "args": [],
      "env": {
        "GOOGLE_SEARCH_TIMEOUT": "15000",
        "MAX_CONTENT_LENGTH": "75000"
      }
    }
  }
}

Claude Desktop Configuration

{
  "mcpServers": {
    "web-search": {
      "command": "/usr/local/bin/web-search-mcp",
      "args": []
    }
  }
}

Best Practices

Query Optimization

  • Use specific, descriptive queries
  • Include relevant keywords
  • Avoid overly broad searches

Result Handling

  • Check for content extraction errors
  • Handle partial failures gracefully
  • Consider result relevance

Error Recovery

  • Implement retry logic for transient errors
  • Provide fallback content when extraction fails
  • Log errors for debugging

Troubleshooting

Common Issues

  1. No Results Returned

    • Check query validity
    • Verify network connectivity
    • Check for rate limiting

  2. Content Extraction Failures

    • Verify URL accessibility
    • Check content encoding
    • Review error messages

  3. Performance Issues

    • Reduce concurrent requests
    • Increase timeout values
    • Check system resources

Debug Mode

Enable debug logging by setting the environment variable:

export DEBUG=web-search-mcp:*

Support

For issues and questions, please log an issue on GitHub.