Efficient Search

An MCP server that calls Google Programmable Search Engine and returns cleaned, structured search results. It decodes HTML entities, extracts available page metadata, adds a short summary, and caches equivalent requests.

Install

npm install -g @om-surushe/efficient-search

You need a Google Programmable Search Engine and a Google API key.

Add the server to your MCP client:

{
  "mcpServers": {
    "efficient-search": {
      "command": "bunx",
      "args": ["@om-surushe/efficient-search"],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "SEARCH_ENGINE_ID": "your_search_engine_id"
      }
    }
  }
}

Tools

| Tool | Purpose | |---|---| | web_search | Search Google with optional result-count, safety, country, and language filters | | clear_cache | Remove all cached responses | | get_cache_stats | Return cache size, capacity, and TTL |

Example request:

{
  "query": "typescript documentation",
  "num": 5,
  "safe": "high",
  "gl": "us",
  "lr": "lang_en"
}

Each result contains its title, URL, cleaned snippet, display host, available metadata, and a score derived from its position in Google's response. The score is not an independent relevance model.

Cache entries are separated by normalized query, result count, safety level, country, and language. The default TTL is 60 minutes.

Configuration

| Variable | Required | Default | Purpose | |---|---:|---:|---| | GOOGLE_API_KEY | Yes | — | Google API key | | SEARCH_ENGINE_ID | Yes | — | Programmable Search Engine ID | | CACHE_TTL_MINUTES | No | 60 | Cache lifetime | | MAX_RESULTS | No | 10 | Default result count |

Google API quotas and Programmable Search Engine coverage still apply. This package does not crawl pages or rerank Google's results.

Development

bun install
bun test
bun run typecheck
bun run build
bun run lint

See CONTRIBUTING.md for repository layout and pull-request guidance.

License

MIT © Om Surushe