mcp-server-googlesearch MCP server

A Model Context Protocol (MCP) server that provides Google search functionality to AI assistants. This server allows AI assistants like Claude to perform web searches and receive structured results with titles, URLs, and descriptions.

Features

• Google Search Tool: Perform web searches using Google's search engine
• Structured Results: Returns search results with title, URL, and description
• Configurable Results: Specify the number of results (1-50, default: 10)
• Error Handling: Comprehensive error handling for network issues, rate limiting, and validation
• MCP Protocol: Full compliance with Model Context Protocol standards

Components

Tools

The server implements one tool:

• google_search: Performs a Google search and returns structured results
  • query (required): The search query to execute
  • num_results (optional): Number of search results to return (1-50, default: 10)

Installation

Prerequisites

• Python 3.11 or higher
• uv package manager

Install from PyPI (when published)

uvx mcp-server-googlesearch

Install from Source

1. Clone or download the project
2. Navigate to the project directory
3. Build and install:

cd mcp-server-googlesearch
uv sync
uv build
uv tool install dist/mcp_server_googlesearch-0.1.0-py3-none-any.whl

Configuration

Claude Desktop

Add the following to your Claude Desktop configuration file:

Windows: %APPDATA%/Claude/claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

For Published Version

{
  "mcpServers": {
    "google-search": {
      "command": "uvx",
      "args": ["mcp-server-googlesearch"]
    }
  }
}

For Development/Local Installation

{
  "mcpServers": {
    "google-search": {
      "command": "uvx",
      "args": [
        "--directory",
        "C:\\path\\to\\mcp-server-googlesearch",
        "mcp-server-googlesearch"
      ]
    }
  }
}

Other MCP Clients

The server can be used with any MCP-compatible client. Use the appropriate command for your setup:

• Direct execution: uvx mcp-server-googlesearch
• From source: uvx --directory /path/to/project mcp-server-googlesearch

Usage Examples

Once configured with your AI assistant, you can use natural language to perform searches:

• "Search for Python programming tutorials"
• "Find information about machine learning"
• "Look up the latest news about artificial intelligence"
• "Search for 'climate change' and show me 5 results"

The server will return formatted results with:

• Numbered list of search results
• Title of each result
• URL of each result
• Description/snippet of each result

Dependencies

• mcp: Model Context Protocol implementation (>=1.12.0)
• googlesearch-python: Google search functionality (>=1.3.0)
• requests: HTTP library (automatically installed with googlesearch-python)
• beautifulsoup4: HTML parsing (automatically installed with googlesearch-python)

Error Handling

The server handles various error conditions gracefully:

• Network Issues: Connection failures, timeouts
• Rate Limiting: Google search rate limits
• Validation Errors: Invalid queries or parameters
• Service Errors: Google service unavailability

All errors are returned as user-friendly messages through the MCP protocol.

Development

Building and Testing

# Sync dependencies
uv sync

# Build the package
uv build

# Install locally for testing
uv tool install dist/mcp_server_googlesearch-0.1.0-py3-none-any.whl

# Test the installation
uvx mcp-server-googlesearch

Debugging

For debugging, you can use the MCP Inspector:

npx @modelcontextprotocol/inspector uvx --directory /path/to/mcp-server-googlesearch mcp-server-googlesearch

This will launch a web interface where you can test the server's functionality.

Troubleshooting

Common Issues

1. Import Errors: Ensure all dependencies are installed with uv sync
2. Network Errors: Check your internet connection and firewall settings
3. Rate Limiting: If you encounter rate limits, wait a moment before trying again
4. Configuration Issues: Verify the path in your Claude Desktop configuration

Logging

The server logs important events and errors. Check the console output or your MCP client's logs for detailed error information.

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Links

• Model Context Protocol Documentation
• Claude Desktop
• googlesearch-python Library