job-search-mcpSearch for jobs across LinkedIn, Indeed, Glassdoor, ZipRecruiter, Google Jobs, Bayt, Naukri, and BDJobs using the JobSpy MCP server.
Install via ClawdBot CLI:
clawdbot install Amoghpurohit/job-search-mcpThis skill enables AI agents to search for jobs across multiple job boards using the JobSpy MCP Server. JobSpy aggregates job listings from LinkedIn, Indeed, Glassdoor, ZipRecruiter, Google Jobs, Bayt, Naukri, and BDJobs into a unified interface.
Use this skill when the user asks you to:
# Install with pip
pip install mcp>=1.1.0 python-jobspy>=1.1.82 pandas>=2.1.0 pydantic>=2.0.0
# Or install with uv (faster)
uv add mcp python-jobspy pandas pydantic# Clone the jobspy-mcp-server repository
git clone https://github.com/chinpeerapat/jobspy-mcp-server.git
cd jobspy-mcp-server
# Install dependencies
uv sync
# or
pip install -e .Add the following to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"jobspy": {
"command": "uv",
"args": ["run", "jobspy-mcp-server"],
"env": {}
}
}
}Alternative configuration (Node.js server):
{
"mcpServers": {
"jobspy": {
"command": "node",
"args": ["/path/to/jobspy-mcp-server/src/index.js"],
"env": {
"ENABLE_SSE": "0"
}
}
}
}scrape_jobs_tool (Primary Tool)Search for jobs across multiple job boards with comprehensive filtering.
Parameters:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| search_term | string | ✅ Yes | - | Job keywords (e.g., "software engineer", "data scientist") |
| location | string | No | - | Job location (e.g., "San Francisco, CA", "Remote") |
| site_name | array | No | ["indeed", "linkedin", "zip_recruiter", "google"] | Job boards to search |
| results_wanted | integer | No | 15 | Number of results (1-1000) |
| job_type | string | No | - | Employment type: fulltime, parttime, internship, contract |
| is_remote | boolean | No | false | Filter for remote jobs only |
| hours_old | integer | No | - | Filter by posting recency in hours |
| distance | integer | No | 50 | Search radius in miles (1-100) |
| easy_apply | boolean | No | false | Filter jobs with easy apply option |
| country_indeed | string | No | "usa" | Country for Indeed/Glassdoor searches |
| linkedin_fetch_description | boolean | No | false | Fetch full LinkedIn descriptions (slower) |
| offset | integer | No | 0 | Pagination offset |
| verbose | integer | No | 1 | Logging level (0=errors, 1=warnings, 2=all) |
Supported Values for site_name:
linkedin - Professional networking platform (rate limited)indeed - Largest job search engine (most reliable)glassdoor - Jobs with company reviews and salarieszip_recruiter - Job matching for US/Canadagoogle - Aggregated job listingsbayt - Middle East job portalnaukri - India's leading job portalbdjobs - Bangladesh job portalSupported Values for job_type:
fulltimeparttimeinternshipcontractget_supported_countriesReturns the complete list of supported countries for job searches. No parameters required.
get_supported_sitesReturns detailed information about all supported job board sites. No parameters required.
get_job_search_tipsReturns tips and best practices for effective job searching. No parameters required.
When jobs are returned, each job post contains the following fields:
interface JobPost {
// Core fields (all platforms)
title: string; // Job title
company: string; // Company name
company_url?: string; // Company website URL
job_url: string; // Direct link to job posting
location: {
country?: string;
city?: string;
state?: string;
};
is_remote: boolean; // Whether job is remote
description?: string; // Job description (markdown format)
job_type?: "fulltime" | "parttime" | "internship" | "contract";
// Salary information
salary?: {
interval?: "yearly" | "monthly" | "weekly" | "daily" | "hourly";
min_amount?: number;
max_amount?: number;
currency?: string;
salary_source?: "direct_data" | "description"; // Parsed from posting
};
date_posted?: string; // ISO date string
emails?: string[]; // Contact emails if available
// LinkedIn specific
job_level?: string; // Seniority level
// LinkedIn & Indeed specific
company_industry?: string;
// Indeed specific
company_country?: string;
company_addresses?: string[];
company_employees_label?: string;
company_revenue_label?: string;
company_description?: string;
company_logo?: string;
// Naukri specific
skills?: string[];
experience_range?: string;
company_rating?: number;
company_reviews_count?: number;
vacancy_count?: number;
work_from_home_type?: string;
}User Prompt:
"Find me 10 software engineer jobs in San Francisco"
MCP Tool Call:
{
"tool": "scrape_jobs_tool",
"params": {
"search_term": "software engineer",
"location": "San Francisco, CA",
"results_wanted": 10,
"site_name": ["indeed", "linkedin"]
}
}Expected Output:
{
"jobs": [
{
"title": "Software Engineer",
"company": "TechCorp Inc.",
"location": { "city": "San Francisco", "state": "CA" },
"job_url": "https://indeed.com/viewjob?jk=abc123",
"salary": { "min_amount": 120000, "max_amount": 180000, "interval": "yearly" },
"job_type": "fulltime",
"is_remote": false
}
// ... more jobs
],
"total_found": 10
}User Prompt:
"Search for remote Python developer positions from Indeed and ZipRecruiter"
MCP Tool Call:
{
"tool": "scrape_jobs_tool",
"params": {
"search_term": "Python developer",
"location": "Remote",
"is_remote": true,
"site_name": ["indeed", "zip_recruiter"],
"results_wanted": 20
}
}User Prompt:
"Find data scientist jobs in Boston posted in the last 24 hours"
MCP Tool Call:
{
"tool": "scrape_jobs_tool",
"params": {
"search_term": "data scientist",
"location": "Boston, MA",
"hours_old": 24,
"site_name": ["linkedin", "glassdoor", "indeed"],
"linkedin_fetch_description": true
}
}User Prompt:
"Look for entry-level marketing jobs in New York with easy apply options"
MCP Tool Call:
{
"tool": "scrape_jobs_tool",
"params": {
"search_term": "junior marketing",
"location": "New York, NY",
"job_type": "fulltime",
"easy_apply": true,
"site_name": ["indeed", "zip_recruiter"],
"results_wanted": 30
}
}User Prompt:
"Find software jobs in Germany on Indeed"
MCP Tool Call:
{
"tool": "scrape_jobs_tool",
"params": {
"search_term": "software developer",
"location": "Berlin",
"country_indeed": "germany",
"site_name": ["indeed"],
"results_wanted": 15
}
}User Prompt:
"What job sites are supported?"
MCP Tool Call:
{
"tool": "get_supported_sites",
"params": {}
}Expected Output:
{
"sites": [
{ "name": "indeed", "description": "Largest job search engine, most reliable" },
{ "name": "linkedin", "description": "Professional networking platform, rate limited" },
{ "name": "glassdoor", "description": "Jobs with company reviews and salaries" },
{ "name": "zip_recruiter", "description": "Job matching for US/Canada" },
{ "name": "google", "description": "Aggregated job listings" },
{ "name": "bayt", "description": "Middle East job portal" },
{ "name": "naukri", "description": "India's leading job portal" },
{ "name": "bdjobs", "description": "Bangladesh job portal" }
]
}Scenario: LinkedIn returns a rate limit error.
Error Response:
{
"error": "RateLimitError",
"message": "LinkedIn rate limit exceeded. Try again later or use different sites.",
"suggestion": "Switch to Indeed or ZipRecruiter which have more lenient rate limits."
}How to Handle:
results_wanted to a smaller number (10-15)linkedin from site_name temporarilyScenario: Search returns empty results.
Error Response:
{
"jobs": [],
"total_found": 0,
"message": "No jobs found matching your criteria"
}How to Handle:
distance radiushours_old or job_typesite_name optionsScenario: User specifies an unsupported country for Indeed.
Error Response:
{
"error": "ValidationError",
"message": "Invalid country_indeed value. Use get_supported_countries to see valid options."
}How to Handle:
get_supported_countries to get valid country codesScenario: User tries to use conflicting filters.
Known Limitations:
hours_old, job_type & is_remote, easy_applyhours_old, easy_applyHow to Handle:
// BAD - Will likely timeout or get rate limited
{
"search_term": "engineer",
"results_wanted": 1000,
"site_name": ["linkedin", "indeed", "glassdoor", "zip_recruiter", "google"]
}Why: Requesting too many results from too many sites simultaneously will trigger rate limits and cause timeouts.
✅ DO INSTEAD:
{
"search_term": "software engineer",
"results_wanted": 20,
"site_name": ["indeed", "linkedin"]
}// BAD - LinkedIn is heavily rate limited
{
"search_term": "developer",
"site_name": ["linkedin"],
"results_wanted": 100,
"linkedin_fetch_description": true
}Why: LinkedIn has the strictest rate limits. Using linkedin_fetch_description: true multiplies requests.
✅ DO INSTEAD:
linkedin_fetch_description when specifically needed// BAD - Indeed limitation: only one filter group allowed
{
"search_term": "developer",
"site_name": ["indeed"],
"hours_old": 24,
"job_type": "fulltime",
"is_remote": true
}Why: Indeed only supports one of: hours_old, job_type & is_remote, or easy_apply.
✅ DO INSTEAD:
// Either filter by recency
{
"search_term": "developer",
"site_name": ["indeed"],
"hours_old": 24
}
// OR filter by job type
{
"search_term": "developer",
"site_name": ["indeed"],
"job_type": "fulltime",
"is_remote": true
}// BAD - Too generic, will return irrelevant results
{
"search_term": "job"
}Why: Vague searches return poor quality results and waste API calls.
✅ DO INSTEAD:
Why: Rate limits, network issues, and invalid parameters require appropriate handling.
✅ DO INSTEAD:
// BAD - Wrong country code format
{
"search_term": "developer",
"country_indeed": "UK" // Wrong! Use "united kingdom"
}✅ DO INSTEAD:
get_supported_countries to verify valid country codesoffset for getting more results instead of high results_wantedCall get_supported_countries for the complete list. Common countries include:
| Country | Code for country_indeed |
|---------|---------------------------|
| USA | usa |
| United Kingdom | united kingdom |
| Canada | canada |
| Germany | germany |
| France | france |
| India | india |
| Australia | australia |
| Singapore | singapore |
| Japan | japan |
| Netherlands | netherlands |
Run: playwright install chromium (some scrapers use Playwright)
Run: pip install python-jobspy>=1.1.82
| User Intent | Key Parameters |
|-------------|----------------|
| Find jobs in a specific city | search_term, location |
| Remote jobs only | is_remote: true |
| Recent postings | hours_old: 24 (or 48, 72) |
| Full-time only | job_type: "fulltime" |
| Quick apply jobs | easy_apply: true |
| Search specific platform | site_name: ["indeed"] |
| International search | country_indeed: "germany" |
| More results | results_wanted: 25 |
| Paginate results | offset: 25 (after first 25) |
Generated Mar 1, 2026
A software engineer looking for remote full-time positions in the US with specific tech stack requirements (e.g., Python, React). This scenario leverages the skill to filter by location, job type, and keywords across platforms like LinkedIn and Indeed, providing tailored results with salary insights and easy-apply options.
A job seeker targeting opportunities in regions like the Middle East or South Asia, using platforms such as Bayt, Naukri, or BDJobs. This scenario involves searching by country, industry, and recent postings to find localized roles with cultural and logistical considerations.
A student or recent graduate seeking internships in fields like marketing or data science. This scenario uses the skill to filter by job type (internship), location, and hours_old for recent postings, helping users find opportunities with company details and application tips.
A professional comparing remote job offerings across multiple sites like Glassdoor and ZipRecruiter to assess salary ranges, company reviews, and job descriptions. This scenario enables side-by-side analysis of listings to make informed career decisions based on aggregated data.
A consultant or freelancer searching for short-term contract positions in industries like healthcare or finance. This scenario utilizes filters for job_type (contract), location, and site_name to find project-based work with detailed posting information and contact emails.
Offer basic job search functionality for free, with premium features like advanced filters, unlimited results, and salary insights for a subscription fee. Revenue is generated through tiered plans targeting individual job seekers and enterprise clients.
Integrate the skill into recruitment agency workflows to automate job sourcing and candidate matching. Revenue comes from service fees charged to companies for streamlined hiring processes and access to aggregated job data across multiple boards.
Combine job search capabilities with personalized coaching, resume optimization, and market trend analysis. Revenue is generated through one-on-one coaching sessions, workshops, and data-driven reports sold to job seekers and educational institutions.
💬 Integration Tip
Ensure the JobSpy MCP server is properly configured in Claude Desktop with the correct command and environment variables to avoid connection issues during job searches.
Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation.
Connect to 100+ APIs (Google Workspace, Microsoft 365, GitHub, Notion, Slack, Airtable, HubSpot, etc.) with managed OAuth. Use this skill when users want to...
Build, debug, and deploy websites using HTML, CSS, JavaScript, and modern frameworks following production best practices.
YouTube Data API integration with managed OAuth. Search videos, manage playlists, access channel data, and interact with comments. Use this skill when users want to interact with YouTube. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
Scaffold, test, document, and debug REST and GraphQL APIs. Use when the user needs to create API endpoints, write integration tests, generate OpenAPI specs, test with curl, mock APIs, or troubleshoot HTTP issues.
This skill should be used when analyzing HTML/CSS websites for SEO optimization, fixing SEO issues, generating SEO reports, or implementing SEO best practices. Use when the user requests SEO audits, optimization, meta tag improvements, schema markup implementation, sitemap generation, or general search engine optimization tasks.