Google Search MCP Server

A Model Context Protocol (MCP) server that provides Google Custom Search functionality.

Configuration

This server uses Dynaconf for configuration management, supporting both .env files and environment variables.

Setup

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env and add your Google API credentials:

   GOOGLE_API_KEY=your_actual_api_key_here GOOGLE_CX=your_custom_search_engine_id_here

Environment Variable Override

Environment variables will override .env file values when both are present. This allows for flexible deployment scenarios:

• Development: Use .env file for local development

• Production: Use environment variables for production deployment

• CI/CD: Environment variables can override defaults for testing

Example:

If your .env file contains:

And you set an environment variable:

The server will use prod_key_from_env (environment variable takes precedence).

Required Configuration

• GOOGLE_API_KEY: Your Google Custom Search API key

• GOOGLE_CX: Your Custom Search Engine ID

Get these from:

• API Key: Google Cloud Console

• Search Engine ID: Google Custom Search

Optional Configuration

• ALLOW_DOMAINS (GOOGLE_ALLOW_DOMAINS env var): Comma-separated list of allowed domains (e.g., example.com, docs.python.org). When set, results outside these domains are filtered out.

• Logging:

  • LOG_QUERIES (GOOGLE_LOG_QUERIES): Enable logging of query hash, timing, and key params.

  • LOG_QUERY_TEXT (GOOGLE_LOG_QUERY_TEXT): Also log full query text (off by default).

  • LOG_LEVEL (GOOGLE_LOG_LEVEL): Set logging level (e.g., INFO, DEBUG).

  • LOG_FILE (GOOGLE_LOG_FILE): Optional path to also write logs to a file (stderr remains enabled).

Usage

Run the server:

Web-based MCP (SSE)

If you are integrating with a browser or any client that uses MCP over HTTP/SSE, run the web server variant:

This exposes the standard MCP endpoints used by web clients:

• GET /sse (Server-Sent Events connection)

• POST /messages (MCP messages)

Notes:

• CORS is enabled by default (CORS_ORIGINS="*"). Customize with CORS_ORIGINS env var.

• Same configuration applies as stdio mode (GOOGLE_API_KEY, GOOGLE_CX, logging flags, etc.).

Run via uvx (no activation, from any folder)

The project exposes a console script google-search-mcp so you can run it with uvx without activating a venv:

Run via pipx (isolated, globally available)

You can also install and run the script with pipx:

Quick start

This project uses httpx with HTTP/2 support enabled for better performance. The dependency is declared as httpx[http2] and will install the h2 package automatically when you sync the environment.

Using uv (recommended)

Try it quickly (no MCP client required)

You can also call the tool function directly for a quick smoke test (uses your env vars):

Note: When using the MCP server with a client, the search tool parameters follow Google CSE semantics. In particular, safe must be one of off or active, and num is clamped to the CSE maximum of 10.

Logging behavior

If LOG_QUERIES is enabled, the server will write a single line per request to stdout containing:

• q_hash (short, non-reversible hash of the query), dt_ms (latency), num, start, safe, and endpoint (cse/siterestrict)

• If LOG_QUERY_TEXT is true, it also includes the full q text.

Example log line:

When a client spawns the server via uvx, logs go to the server process’s stderr by default (safe for MCP stdio). To persist logs regardless of the client’s stderr handling:

• Set a file path (absolute recommended):

  GOOGLE_LOG_QUERIES=true GOOGLE_LOG_FILE=/var/log/google_search_mcp.log

• Or redirect stderr in the launch command:

  uvx --from /path/to/repo google-search-mcp 2>> /tmp/google_search_mcp.log

Streamable HTTP Variant

For clients that use StreamableHttpServerParams (non-SSE MCP over HTTP), run the Streamable HTTP server variant:

Client usage example with the official MCP streamable HTTP transport:

Notes:

• Endpoints are managed by FastMCP; you should not call /sse for this variant.

• CORS is enabled and configurable with CORS_ORIGINS.

Testing

Unit Tests

Run the test suite to validate functionality:

Testing

Unit Tests

Run the test suite to validate functionality:

Local Testing

Test the server locally using the MCP Inspector or direct HTTP calls:

Testing

The project includes a comprehensive test suite located in the tests/ directory. All tests use pytest and mock external dependencies for reliable, fast execution.

Unit Tests

Run the comprehensive test suite to validate functionality:

Local Testing

Test the server locally using the MCP Inspector or direct HTTP calls:

AWS Gateway Testing

For AWS AgentCore Gateway deployments, use the dedicated test script:

This validates authentication, tool listing, and tool execution through the gateway.

AWS Lambda Deployment

Deploy this MCP server to AWS Lambda and integrate with Bedrock AgentCore Gateway:

Known Issues

Environment Variable Inheritance (RESOLVED): There was an issue where environment variables set in the Lambda function were not properly inherited by the MCP server subprocess. This has been resolved by explicitly passing environment variables through the

The Lambda handler now correctly passes environment variables to the MCP server subprocess, ensuring tool calls work properly.

AgentCore Gateway Integration

The Gateway uses JSON-RPC 2.0 protocol (not standard MCP HTTP endpoints). Authentication requires:

• Cognito client credentials OAuth flow

• Token endpoint format: https://domain.auth.region.amazoncognito.com/oauth2/token

• Proper JSON-RPC 2.0 request format for tool operations

See deploy/README-lambda-zip.md for detailed deployment instructions, including cross-platform builds, infrastructure as code, and AgentCore Gateway integration.

Note: AgentCore Gateway compute targets and MCP providers currently require manual console configuration as APIs are not publicly available.