JobSpy MCP Server Stack

A production-ready Model Context Protocol (MCP) server for job searching across multiple job boards, built with JobSpy and containerized for easy deployment.

🚀 Features

• Multi-platform job search: LinkedIn, Indeed, Glassdoor, ZipRecruiter, Google Jobs, Bayt, Naukri, BDJobs
• MCP Protocol: Standard interface for AI assistants (Claude Desktop, Claude Code)
• Docker containerized: Easy deployment and scaling
• LAN-safe: Secure local network access only
• No API keys required: JobSpy handles all authentication internally

🏗️ Architecture

┌─────────────────┐    TCP:8500     ┌──────────────────────┐
│   Claude Code   │◄──────────────►│   MCP Server Stack   │
│  Claude Desktop │                │                      │
└─────────────────┘                │  ┌─────────────────┐ │
                                   │  │  JobSpy MCP     │ │
                                   │  │    Server       │ │
                                   │  └─────────────────┘ │
                                   │                      │
                                   │  ┌─────────────────┐ │
                                   │  │ Future MCP      │ │
                                   │  │   Servers       │ │
                                   │  └─────────────────┘ │
                                   └──────────────────────┘

🛠️ Quick Start

Prerequisites

• Docker & Docker Compose
• Linux/macOS (tested on Ubuntu/Debian)
• Network access to job boards

1. Clone and Deploy

git clone https://github.com/YOUR_USERNAME/jobspy-mcp-stack.git
cd jobspy-mcp-stack
docker-compose up -d

2. Verify Deployment

# Check container status
docker-compose ps

# Test connection
telnet localhost 8500

3. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jobspy": {
      "command": "nc",
      "args": ["YOUR_SERVER_LAN_IP", "8500"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Replace YOUR_SERVER_LAN_IP with your server's LAN IP (e.g., 192.168.1.100).

4. Configure Claude Code

Connect to MCP server:

• Host: YOUR_SERVER_LAN_IP
• Port: 8500
• Protocol: TCP
• Authentication: None

📚 Available Tools

search_jobs

Search for job postings across multiple job boards.

Parameters:

• search_term (required): Job title or keywords
• location (optional): Location to search in
• site_name (optional): Job boards to search (default: ["indeed", "linkedin"])
• results_wanted (optional): Number of results per site (1-100, default: 20)
• job_type (optional): "fulltime", "parttime", "internship", "contract"
• is_remote (optional): Filter for remote jobs
• distance (optional): Search radius in miles (default: 50)
• hours_old (optional): Filter jobs posted within X hours
• country_indeed (optional): Country for Indeed/Glassdoor (default: "usa")

Example:

Search for software engineer jobs in San Francisco with remote options

get_job_details

Get detailed information about a specific job posting (planned feature).

🌍 Supported Job Boards

Job Board	Coverage	Rate Limits
Indeed	Global, best performance	Minimal
LinkedIn	Global	Moderate (use proxies for heavy usage)
Glassdoor	Most countries	Moderate
ZipRecruiter	US/Canada	Low
Google Jobs	Global (specific syntax)	Low
Bayt	Middle East	Low
Naukri	India	Low
BDJobs	Bangladesh	Low

🔧 Configuration

Environment Variables

environment:
  - PYTHONUNBUFFERED=1
  - LOG_LEVEL=INFO

Port Configuration

• 8500: JobSpy MCP Server
• 8501-8510: Reserved for future MCP servers

Custom Job Search

The server supports all JobSpy parameters. See JobSpy documentation for advanced usage.

🚀 Deployment Options

Local Development

docker-compose up

Production

docker-compose up -d --restart unless-stopped

Adding New MCP Servers

1. Create your MCP server in a new directory
2. Add service to docker-compose.yml:

your-mcp:
  build: ../YourMCPServer
  container_name: mcp-your-server
  ports:
    - "8501:8501"
  networks:
    - mcp-network
  restart: unless-stopped

📊 Monitoring

Container Status

docker-compose ps
docker-compose logs -f

Resource Usage

docker stats mcp-jobspy-server

Network Connectivity

# Test TCP connection
nc -zv YOUR_SERVER_IP 8500

# Test MCP protocol
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | nc YOUR_SERVER_IP 8500

🛡️ Security

• LAN-only access: Server binds to private network interfaces
• Container isolation: Runs with non-root user
• No external credentials: No API keys or tokens stored
• Firewall friendly: Single port exposure

🔄 Updates

Update JobSpy

docker-compose down
docker-compose build --no-cache
docker-compose up -d

Update Stack

git pull origin main
docker-compose down
docker-compose up -d --build

🐛 Troubleshooting

Common Issues

Container won't start:

docker-compose logs jobspy-mcp

Port conflicts:

netstat -tuln | grep 8500
# Change port in docker-compose.yml if needed

Connection refused:

# Check if container is running
docker-compose ps

# Check port binding
docker port mcp-jobspy-server

Job search returns no results:

• Verify internet connectivity
• Try different job boards
• Check search parameters
• Some job boards may be temporarily blocking

Debug Mode

Enable verbose logging:

environment:
  - LOG_LEVEL=DEBUG
  - PYTHONUNBUFFERED=1

📈 Performance

Optimization Tips

1. Rate Limiting: JobSpy handles rate limiting internally
2. Proxies: For heavy usage, configure proxy rotation
3. Caching: Results are not cached by default
4. Concurrency: JobSpy searches job boards concurrently

Resource Requirements

• CPU: 1 core minimum, 2+ recommended
• RAM: 512MB minimum, 1GB+ recommended
• Storage: 2GB for container and logs
• Network: Stable internet connection

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with docker-compose up --build
5. Submit a pull request

📄 License

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

🙏 Acknowledgments

• JobSpy - Core job scraping library
• MCP - Model Context Protocol
• Anthropic - Claude AI development

📞 Support

• Create an Issue for bug reports
• Check JobSpy documentation for scraping issues
• Review MCP specification for protocol questions

---

Built with ❤️ for the AI community