Google PSE MCP Server

Instructions

Implementation Reference

• src/index.ts:79-160 (handler)

  The core handler logic for the 'search' tool. Processes input arguments, builds and sends a request to the Google Custom Search API (site-restricted or standard), handles errors, and returns search results as formatted JSON.
  if (request.params.name === "search") { const args = request.params.arguments as any; const { q, page = 1, size = 10, lr, safe = false, sort } = args; if (!q) { throw new Error("Missing required argument: q"); } if (!API_KEY) { throw new Error("API_KEY is not configured"); } if (!CX) { throw new Error("CX is not configured"); } // Build query params const params = new URLSearchParams(); params.append("key", API_KEY); params.append("cx", CX); params.append("q", q); params.append("fields", "items(title,htmlTitle,link,snippet,htmlSnippet)"); // Language restriction if (lr !== undefined) { params.append("lr", String(lr)); } // SafeSearch mapping (boolean only) if (safe !== undefined) { if (typeof safe !== "boolean") { throw new Error("SafeSearch (safe) must be a boolean"); } params.append("safe", safe ? "active" : "off"); } // Sort validation if (sort !== undefined) { if (sort === "date") { params.append("sort", "date"); } else { throw new Error("Only 'date' is supported for sort"); } } // Pagination params.append("num", String(size)); if (page > 0 && size > 0) { const start = ((page - 1) * size) + 1; params.append("start", String(start)); } else { params.append("start", "1"); } const siteRestricted = args.siteRestricted !== undefined ? args.siteRestricted : SITE_RESTRICTED_DEFAULT; const endpoint = siteRestricted ? "/v1/siterestrict" : "/v1"; const url = `${API_HOST}${endpoint}?${params.toString()}`; const response = await fetch(url, { method: "GET" }); if (!response.ok) { throw new Error(`Search API request failed: ${response.status} ${response.statusText}`); } const result = await response.json(); // Return the items array (list of articles) const items = result?.items ?? []; return { content: [{ type: "text", text: JSON.stringify(items, null, 2) }] }; }
• src/index.ts:43-68 (schema)

  Tool schema definition including name, description, and detailed inputSchema with properties, types, descriptions, and required fields for the 'search' tool.
  { name: "search", description: "Search the Web using Google Custom Search API", inputSchema: { type: "object", properties: { q: { type: "string", description: "Search query" }, page: { type: "integer", description: "Page number" }, size: { type: "integer", description: "Number of search results to return per page. Valid values are integers between 1 and 10, inclusive." }, sort: { type: "string", description: "Sort expression (e.g., 'date'). Only 'date' is supported by the API." }, safe: { type: "boolean", description: "Enable safe search filtering. Default: false." }, lr: { type: "string", description: "Restricts the search to documents written in a particular language (e.g., lang_en, lang_ja)" }, siteRestricted: { type: "boolean", description: "If true, use the Site Restricted API endpoint (/v1/siterestrict). If false, use the standard API endpoint (/v1). Default: true." }, }, required: ["q"] } }
• src/index.ts:40-71 (registration)

  Registers the 'search' tool with the MCP server by handling ListToolsRequestSchema and returning the tool specification in the tools array.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "search", description: "Search the Web using Google Custom Search API", inputSchema: { type: "object", properties: { q: { type: "string", description: "Search query" }, page: { type: "integer", description: "Page number" }, size: { type: "integer", description: "Number of search results to return per page. Valid values are integers between 1 and 10, inclusive." }, sort: { type: "string", description: "Sort expression (e.g., 'date'). Only 'date' is supported by the API." }, safe: { type: "boolean", description: "Enable safe search filtering. Default: false." }, lr: { type: "string", description: "Restricts the search to documents written in a particular language (e.g., lang_en, lang_ja)" }, siteRestricted: { type: "boolean", description: "If true, use the Site Restricted API endpoint (/v1/siterestrict). If false, use the standard API endpoint (/v1). Default: true." }, }, required: ["q"] } } ] }; });