mcp-server-googlesearch 0.1.1
A Model Context Protocol server that provides Google search functionality to AI assistants
Requires Python: >=3.11

# 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)

```bash
uvx mcp-server-googlesearch
```

### Install from Source

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

```bash
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

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

#### For Development/Local Installation

```json
{
  "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

```bash
# 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:

```bash
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](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/desktop)
- [googlesearch-python Library](https://pypi.org/project/googlesearch-python/)