Google Jobs MCP Server

Instructions

Implementation Reference

• src/index.ts:130-224 (schema)

  Defines the tool metadata, description, and detailed input schema with parameters, types, descriptions, and defaults for the search_jobs tool.
  const SEARCH_JOBS_TOOL = { name: "search_jobs", description: `Google Jobs API search tool. Supported search parameters: 1. Basic Search: Job title or keywords 2. Location: City or region 3. Time Filter: Recently posted jobs 4. Job Type: Full-time, part-time, contract, internship 5. Salary Range: Filter by compensation 6. Geographic Range: Set search radius 7. Language: Multi-language support All parameters except 'query' are optional and can be freely combined.`, inputSchema: { type: "object", properties: { query: { type: "string", description: "Search keywords (Required, e.g., 'software engineer', 'data analyst', 'product manager')" }, location: { type: "string", description: "Job location (Optional, e.g., 'New York', 'London', 'Tokyo')", default: "" }, posted_age: { type: "string", description: `Posting date filter (Optional) Options: - "today": Posted today - "3days": Last 3 days - "week": Last week - "month": Last month`, default: "" }, employment_type: { type: "string", description: `Job type (Optional) Options: - "FULLTIME": Full-time - "PARTTIME": Part-time - "CONTRACTOR": Contractor - "INTERN": Internship - "TEMPORARY": Temporary`, default: "" }, salary: { type: "string", description: `Salary range (Optional) Format examples: - "$50K+": Above $50,000 - "$100K+": Above $100,000 - "$150K+": Above $150,000`, default: "" }, radius: { type: "string", description: `Search radius (Optional) Format examples: - "10mi": Within 10 miles - "20mi": Within 20 miles - "50mi": Within 50 miles`, default: "" }, hl: { type: "string", description: `Result language (Optional) Options: - "en": English - "zh-CN": Chinese - "ja": Japanese - "ko": Korean`, default: "en" }, page: { type: "number", description: `Page number (Optional, default: 1) - 10 results per page - Supports pagination`, default: 1 }, sort_by: { type: "string", description: `Sort order (Optional) Options: - "date": Sort by date - "relevance": Sort by relevance - "salary": Sort by salary`, default: "relevance" } }, required: ["query"] } };
• src/index.ts:448-450 (registration)

  Registers the search_jobs tool object in the MCP server's ListTools request handler.
  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [SEARCH_JOBS_TOOL] }));
• src/index.ts:452-493 (handler)

  MCP CallToolRequestSchema handler that validates the tool name and arguments, calls performJobSearch for search_jobs, handles success/error responses with localized error messages.
  server.setRequestHandler(CallToolRequestSchema, async (request) => { try { const { name, arguments: args } = request.params; if (name !== "search_jobs") { throw new Error("Unknown tool"); } if (!args || typeof args.query !== "string") { throw new Error("Invalid arguments for search_jobs"); } const results = await performJobSearch( args.query, args.location as string | undefined, args.posted_age as string | undefined, args.employment_type as string | undefined, args.salary as string | undefined, args.radius as string | undefined, args.hl as SupportedLanguage | undefined ); return { content: [{ type: "text", text: results }], isError: false }; } catch (error) { const args = request.params.arguments as { query?: string; hl?: SupportedLanguage } | undefined; const query = args?.query || ""; const lang = args?.hl || "en"; const t = getLocalizedText(lang); const suggestions = getSearchSuggestions(error, query, lang); return { content: [{ type: "text", text: `❌ ${t.error}:\n${error instanceof Error ? error.message : String(error)}\n${suggestions}` }], isError: true }; } });
• src/index.ts:372-445 (handler)

  Core handler function for search_jobs: validates params, constructs SerpAPI Google Jobs URL with filters, fetches and parses JSON response, formats output using helper functions.
  async function performJobSearch( query: string, location?: string, posted_age?: string, employment_type?: string, salary?: string, radius?: string, hl?: SupportedLanguage ) { // Parameter validation const warnings = validateSearchParams({ query, location, salary, radius }, hl); let output = ""; if (warnings.length > 0) { const t = getLocalizedText(hl); output += `⚠️ ${t.warning}:\n`; warnings.forEach(warning => { output += `• ${warning}\n`; }); output += `\n`; } // Build search URL const url = new URL('https://serpapi.com/search'); url.searchParams.set('engine', 'google_jobs'); url.searchParams.set('q', query); url.searchParams.set('api_key', SERP_API_KEY as string); // Add basic parameters if (location) { url.searchParams.set('location', location); } if (posted_age) { url.searchParams.set('chips', `date_posted:${posted_age}`); } // Add additional parameters if (employment_type) { url.searchParams.append('chips', `employment_type:${employment_type}`); } if (salary) { url.searchParams.append('chips', `salary:${salary}`); } if (radius) { url.searchParams.set('location_distance', radius); } if (hl) { url.searchParams.set('hl', hl); } // Make API request const response = await fetch(url.toString()); if (!response.ok) { throw new Error(`Serp API error: ${response.status} ${response.statusText}`); } // Process response const data = await response.json() as JobSearchResponse; return output + formatJobResults( data.jobs_results || [], data.search_metadata || {}, data.page || 1, hl ); }