jobspy-mcp-server by chinpeerapat - MCP Server

JobSpy MCP Server

A modern MCP (Model Context Protocol) server that provides job scraping capabilities using the JobSpy library. Built with the latest FastMCP framework for seamless integration with Claude Desktop and other MCP clients.

🚀 Features

Multi-site job scraping: Search across 8 major job boards (LinkedIn, Indeed, Glassdoor, ZipRecruiter, Google Jobs, Bayt, Naukri, BDJobs)
Advanced filtering: Filter by job type, location, posting date, remote work, salary range, and more
Real-time progress: Get live updates during job searches with progress indicators
Rich formatting: Beautifully formatted job results with all relevant details
Modern MCP implementation: Built with FastMCP for 2025 MCP protocol compliance
Error handling: Robust error handling with informative messages
Comprehensive tools: Multiple tools for job searching, country/site information, and search tips

📦 Installation

Prerequisites

Python 3.10 or higher
uv (recommended) or pip

Quick Install

# Clone or download the project
cd jobspy-mcp-server

# Install with uv (recommended)
uv sync

# Or install with pip
pip install -e .

Install Dependencies Manually

pip install mcp>=1.1.0 python-jobspy>=1.1.82 pandas>=2.1.0 pydantic>=2.0.0

🔧 Usage

Run with uv (Recommended)

# Development mode with auto-reload
uv run mcp dev -m jobspy_mcp_server

# Production mode
uv run mcp run -m jobspy_mcp_server

# Direct execution
uv run python -m jobspy_mcp_server

Run with Python

python -m jobspy_mcp_server

Install in Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "jobspy": {
      "command": "uv",
      "args": ["run", "jobspy-mcp-server"]
    }
  }
}

Alternative configuration (if installed globally):

{
  "mcpServers": {
    "jobspy": {
      "command": "jobspy-mcp-server"
    }
  }
}

Alternative configuration (direct Python execution):

{
  "mcpServers": {
    "jobspy": {
      "command": "python",
      "args": ["-m", "jobspy_mcp_server"]
    }
  }
}

🛠️ Available Tools

1. `scrape_jobs_tool`

Search for jobs across multiple job boards with comprehensive filtering options.

Parameters:

search_term (required): Job keywords (e.g., "software engineer", "data scientist")
location: Job location (e.g., "San Francisco, CA", "Remote")
site_name: List of job boards to search (default: ["indeed", "linkedin", "zip_recruiter", "google"])
results_wanted: Number of results (1-1000, default: 15)
job_type: Employment type ("fulltime", "parttime", "internship", "contract")
is_remote: Filter remote jobs only (default: false)
hours_old: Filter by posting recency in hours
distance: Search radius in miles (1-100, default: 50)
easy_apply: Filter jobs with easy apply (default: false)
country_indeed: Country for Indeed/Glassdoor (default: "usa")
linkedin_fetch_description: Get full LinkedIn descriptions (slower, default: false)
offset: Pagination offset (default: 0)
verbose: Logging level (0-2, default: 1)

2. `get_supported_countries`

Get the complete list of supported countries for job searches.

3. `get_supported_sites`

Get detailed information about all supported job board sites.

4. `get_job_search_tips`

Get comprehensive tips and best practices for effective job searching.

💡 Example Queries

Ask Claude:

"Find me 25 remote Python developer jobs from Indeed and LinkedIn"

"Search for data scientist positions in San Francisco posted in the last 48 hours"

"Look for entry-level marketing jobs in New York with easy apply options"

"Show me all supported job sites and their descriptions"

"Give me tips for searching software engineering jobs effectively"

🌍 Supported Job Boards

LinkedIn: Professional networking platform (rate limited)
Indeed: Largest job search engine (most reliable)
Glassdoor: Jobs with company reviews and salaries
ZipRecruiter: Job matching for US/Canada
Google Jobs: Aggregated job listings
Bayt: Middle East job portal
Naukri: India's leading job portal
BDJobs: Bangladesh job portal

🌎 Supported Countries

The server supports 50+ countries including:

USA, Canada, UK, Australia
Germany, France, Spain, Italy
India, Singapore, Japan, South Korea
And many more...

Use get_supported_countries tool for the complete list.

🚨 Rate Limiting & Best Practices

LinkedIn: Most restrictive, use sparingly
Indeed: Most reliable, good for large searches
Start small: Begin with 10-15 results
Use filtering: Leverage job_type, hours_old, is_remote filters
Be specific: Use targeted search terms for better results

🔍 Advanced Search Examples

Remote Software Jobs

{
  "search_term": "software engineer",
  "location": "Remote", 
  "is_remote": true,
  "site_name": ["indeed", "zip_recruiter"],
  "results_wanted": 20
}

Recent Data Science Jobs

{
  "search_term": "data scientist",
  "location": "San Francisco, CA",
  "hours_old": 48,
  "site_name": ["linkedin", "glassdoor"],
  "linkedin_fetch_description": true
}

Entry Level Positions

{
  "search_term": "junior developer",
  "job_type": "fulltime",
  "easy_apply": true,
  "site_name": ["indeed", "zip_recruiter"],
  "results_wanted": 30
}

🧪 Testing

Run the test suite:

# With uv
uv run pytest

# With pip
pip install pytest
pytest

# Run specific tests
uv run pytest test_jobspy_mcp.py -v

# Run integration tests only
uv run pytest test_jobspy_mcp.py::TestJobSpyIntegration -v

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔧 Troubleshooting

Common Issues

"Module not found" errors

Ensure all dependencies are installed: uv sync or pip install -e .

"No results found"

Try broader search terms
Check different job boards
Verify location spelling

Rate limiting/blocking

Reduce results_wanted parameter
Use different job boards (avoid LinkedIn for large searches)
Add delays between searches

Claude Desktop not detecting tools

Verify configuration file path and JSON syntax
Restart Claude Desktop after configuration changes
Check server logs for errors

Getting Help

Check the comprehensive get_job_search_tips tool
Review the example queries above
Start with small searches and expand gradually
Use verbose logging (verbose=2) for debugging

🚀 Quick Start

Install: uv sync
Test: uv run mcp dev -m jobspy_mcp_server
Configure Claude Desktop with the server

🐍 Direct Python Execution

After installation, you can also run the server directly:

# Run with Python module syntax
python -m jobspy_mcp_server

# Run with uv
uv run python -m jobspy_mcp_server

Ask Claude: "Find me remote Python jobs using JobSpy"

Happy job hunting! 🎯

chinpeerapat/jobspy-mcp-server