| Name | jobspy-mcp-server JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | MCP server for JobSpy job scraping library |
| upload_time | 2025-08-04 06:11:41 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2025 JobSpy MCP Server
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
jobs
jobspy
mcp
scraping
server
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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
```bash
# 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
```bash
pip install mcp>=1.1.0 python-jobspy>=1.1.82 pandas>=2.1.0 pydantic>=2.0.0
```
## 🔧 Usage
### Run with uv (Recommended)
```bash
# Development mode with auto-reload
uv run mcp dev server.py
# Production mode
uv run mcp run server.py
# Direct execution
uv run python server.py
```
### Run with Python
```bash
python server.py
```
### 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`
```json
{
"mcpServers": {
"jobspy": {
"command": "uv",
"args": ["run", "python", "/full/path/to/jobspy-mcp-server/server.py"]
}
}
}
```
Alternative configuration:
```json
{
"mcpServers": {
"jobspy": {
"command": "python",
"args": ["/full/path/to/jobspy-mcp-server/server.py"]
}
}
}
```
## 🛠️ 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
```json
{
"search_term": "software engineer",
"location": "Remote",
"is_remote": true,
"site_name": ["indeed", "zip_recruiter"],
"results_wanted": 20
}
```
### Recent Data Science Jobs
```json
{
"search_term": "data scientist",
"location": "San Francisco, CA",
"hours_old": 48,
"site_name": ["linkedin", "glassdoor"],
"linkedin_fetch_description": true
}
```
### Entry Level Positions
```json
{
"search_term": "junior developer",
"job_type": "fulltime",
"easy_apply": true,
"site_name": ["indeed", "zip_recruiter"],
"results_wanted": 30
}
```
## 🧪 Testing
Run the test suite:
```bash
# With uv
uv run pytest
# With pip
pip install pytest
pytest
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. 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
1. Check the comprehensive `get_job_search_tips` tool
2. Review the example queries above
3. Start with small searches and expand gradually
4. Use verbose logging (`verbose=2`) for debugging
## 🚀 Quick Start
1. Install: `uv sync`
2. Test: `uv run mcp dev server.py`
3. Configure Claude Desktop with the server path
4. Ask Claude: "Find me remote Python jobs using JobSpy"
Happy job hunting! 🎯
Raw data
{
"_id": null,
"home_page": null,
"name": "jobspy-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "jobs, jobspy, mcp, scraping, server",
"author": null,
"author_email": "JobSpy MCP <jobspy@example.com>",
"download_url": "https://files.pythonhosted.org/packages/8c/63/370358c2802186cf63d5ed091914abe0c0711c67515963f6bf0fc0fed279/jobspy_mcp_server-1.0.0.tar.gz",
"platform": null,
"description": "# JobSpy MCP Server\n\nA 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.\n\n## \ud83d\ude80 Features\n\n- **Multi-site job scraping**: Search across 8 major job boards (LinkedIn, Indeed, Glassdoor, ZipRecruiter, Google Jobs, Bayt, Naukri, BDJobs)\n- **Advanced filtering**: Filter by job type, location, posting date, remote work, salary range, and more\n- **Real-time progress**: Get live updates during job searches with progress indicators\n- **Rich formatting**: Beautifully formatted job results with all relevant details\n- **Modern MCP implementation**: Built with FastMCP for 2025 MCP protocol compliance\n- **Error handling**: Robust error handling with informative messages\n- **Comprehensive tools**: Multiple tools for job searching, country/site information, and search tips\n\n## \ud83d\udce6 Installation\n\n### Prerequisites\n- Python 3.10 or higher\n- uv (recommended) or pip\n\n### Quick Install\n```bash\n# Clone or download the project\ncd jobspy-mcp-server\n\n# Install with uv (recommended)\nuv sync\n\n# Or install with pip\npip install -e .\n```\n\n### Install Dependencies Manually\n```bash\npip install mcp>=1.1.0 python-jobspy>=1.1.82 pandas>=2.1.0 pydantic>=2.0.0\n```\n\n## \ud83d\udd27 Usage\n\n### Run with uv (Recommended)\n```bash\n# Development mode with auto-reload\nuv run mcp dev server.py\n\n# Production mode\nuv run mcp run server.py\n\n# Direct execution\nuv run python server.py\n```\n\n### Run with Python\n```bash\npython server.py\n```\n\n### Install in Claude Desktop\nAdd to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"jobspy\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"/full/path/to/jobspy-mcp-server/server.py\"]\n }\n }\n}\n```\n\nAlternative configuration:\n```json\n{\n \"mcpServers\": {\n \"jobspy\": {\n \"command\": \"python\",\n \"args\": [\"/full/path/to/jobspy-mcp-server/server.py\"]\n }\n }\n}\n```\n\n## \ud83d\udee0\ufe0f Available Tools\n\n### 1. `scrape_jobs_tool`\nSearch for jobs across multiple job boards with comprehensive filtering options.\n\n**Parameters:**\n- `search_term` (required): Job keywords (e.g., \"software engineer\", \"data scientist\")\n- `location`: Job location (e.g., \"San Francisco, CA\", \"Remote\")\n- `site_name`: List of job boards to search (default: [\"indeed\", \"linkedin\", \"zip_recruiter\", \"google\"])\n- `results_wanted`: Number of results (1-1000, default: 15)\n- `job_type`: Employment type (\"fulltime\", \"parttime\", \"internship\", \"contract\")\n- `is_remote`: Filter remote jobs only (default: false)\n- `hours_old`: Filter by posting recency in hours\n- `distance`: Search radius in miles (1-100, default: 50)\n- `easy_apply`: Filter jobs with easy apply (default: false)\n- `country_indeed`: Country for Indeed/Glassdoor (default: \"usa\")\n- `linkedin_fetch_description`: Get full LinkedIn descriptions (slower, default: false)\n- `offset`: Pagination offset (default: 0)\n- `verbose`: Logging level (0-2, default: 1)\n\n### 2. `get_supported_countries`\nGet the complete list of supported countries for job searches.\n\n### 3. `get_supported_sites`\nGet detailed information about all supported job board sites.\n\n### 4. `get_job_search_tips`\nGet comprehensive tips and best practices for effective job searching.\n\n## \ud83d\udca1 Example Queries\n\nAsk Claude:\n\n> \"Find me 25 remote Python developer jobs from Indeed and LinkedIn\"\n\n> \"Search for data scientist positions in San Francisco posted in the last 48 hours\"\n\n> \"Look for entry-level marketing jobs in New York with easy apply options\"\n\n> \"Show me all supported job sites and their descriptions\"\n\n> \"Give me tips for searching software engineering jobs effectively\"\n\n## \ud83c\udf0d Supported Job Boards\n\n- **LinkedIn**: Professional networking platform (rate limited) \n- **Indeed**: Largest job search engine (most reliable)\n- **Glassdoor**: Jobs with company reviews and salaries\n- **ZipRecruiter**: Job matching for US/Canada\n- **Google Jobs**: Aggregated job listings \n- **Bayt**: Middle East job portal\n- **Naukri**: India's leading job portal\n- **BDJobs**: Bangladesh job portal\n\n## \ud83c\udf0e Supported Countries\n\nThe server supports 50+ countries including:\n- USA, Canada, UK, Australia\n- Germany, France, Spain, Italy\n- India, Singapore, Japan, South Korea\n- And many more...\n\nUse `get_supported_countries` tool for the complete list.\n\n## \ud83d\udea8 Rate Limiting & Best Practices\n\n- **LinkedIn**: Most restrictive, use sparingly\n- **Indeed**: Most reliable, good for large searches\n- **Start small**: Begin with 10-15 results\n- **Use filtering**: Leverage job_type, hours_old, is_remote filters\n- **Be specific**: Use targeted search terms for better results\n\n## \ud83d\udd0d Advanced Search Examples\n\n### Remote Software Jobs\n```json\n{\n \"search_term\": \"software engineer\",\n \"location\": \"Remote\", \n \"is_remote\": true,\n \"site_name\": [\"indeed\", \"zip_recruiter\"],\n \"results_wanted\": 20\n}\n```\n\n### Recent Data Science Jobs\n```json\n{\n \"search_term\": \"data scientist\",\n \"location\": \"San Francisco, CA\",\n \"hours_old\": 48,\n \"site_name\": [\"linkedin\", \"glassdoor\"],\n \"linkedin_fetch_description\": true\n}\n```\n\n### Entry Level Positions\n```json\n{\n \"search_term\": \"junior developer\",\n \"job_type\": \"fulltime\",\n \"easy_apply\": true,\n \"site_name\": [\"indeed\", \"zip_recruiter\"],\n \"results_wanted\": 30\n}\n```\n\n## \ud83e\uddea Testing\n\nRun the test suite:\n```bash\n# With uv\nuv run pytest\n\n# With pip\npip install pytest\npytest\n```\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## \ud83d\udd27 Troubleshooting\n\n### Common Issues\n\n**\"Module not found\" errors**\n- Ensure all dependencies are installed: `uv sync` or `pip install -e .`\n\n**\"No results found\"**\n- Try broader search terms\n- Check different job boards\n- Verify location spelling\n\n**Rate limiting/blocking**\n- Reduce `results_wanted` parameter\n- Use different job boards (avoid LinkedIn for large searches)\n- Add delays between searches\n\n**Claude Desktop not detecting tools**\n- Verify configuration file path and JSON syntax\n- Restart Claude Desktop after configuration changes\n- Check server logs for errors\n\n### Getting Help\n\n1. Check the comprehensive `get_job_search_tips` tool\n2. Review the example queries above\n3. Start with small searches and expand gradually\n4. Use verbose logging (`verbose=2`) for debugging\n\n## \ud83d\ude80 Quick Start\n\n1. Install: `uv sync`\n2. Test: `uv run mcp dev server.py` \n3. Configure Claude Desktop with the server path\n4. Ask Claude: \"Find me remote Python jobs using JobSpy\"\n\nHappy job hunting! \ud83c\udfaf\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 JobSpy MCP Server\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "MCP server for JobSpy job scraping library",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/yourorg/jobspy-mcp-server",
"Source": "https://github.com/yourorg/jobspy-mcp-server"
},
"split_keywords": [
"jobs",
" jobspy",
" mcp",
" scraping",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1c1ff283e4f0a55c9b569729aa0a8e1d3d66201ed00aba208bbdb8efe2bb4b16",
"md5": "1f34f451cad55515630ac68848204955",
"sha256": "6add6111916939203940c3843f65bba596171069751f1e70488ae75118719363"
},
"downloads": -1,
"filename": "jobspy_mcp_server-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1f34f451cad55515630ac68848204955",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11262,
"upload_time": "2025-08-04T06:11:39",
"upload_time_iso_8601": "2025-08-04T06:11:39.786100Z",
"url": "https://files.pythonhosted.org/packages/1c/1f/f283e4f0a55c9b569729aa0a8e1d3d66201ed00aba208bbdb8efe2bb4b16/jobspy_mcp_server-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8c63370358c2802186cf63d5ed091914abe0c0711c67515963f6bf0fc0fed279",
"md5": "e3f37f1abdcbffa8f7bbda567f02d48f",
"sha256": "715b1c3ce365d207f74b9bb0533cb96b2c2acca537212656910b13104f58b5e8"
},
"downloads": -1,
"filename": "jobspy_mcp_server-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "e3f37f1abdcbffa8f7bbda567f02d48f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 22426,
"upload_time": "2025-08-04T06:11:41",
"upload_time_iso_8601": "2025-08-04T06:11:41.339467Z",
"url": "https://files.pythonhosted.org/packages/8c/63/370358c2802186cf63d5ed091914abe0c0711c67515963f6bf0fc0fed279/jobspy_mcp_server-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 06:11:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourorg",
"github_project": "jobspy-mcp-server",
"github_not_found": true,
"lcname": "jobspy-mcp-server"
}
