Content
# JobSpy MCP Server
A Model Context Protocol (MCP) server that enables AI assistants like Claude to search for jobs across multiple job listing platforms using the [JobSpy](https://github.com/yourusername/jobspy) tool.
## Features
- Search for jobs across multiple platforms (Indeed, LinkedIn, Glassdoor, etc.)
- Filter by search terms, location, time frames, and more
- Get structured job data that AI models can easily process
- Format results as JSON or CSV
- Multiple transport options: stdio for Claude integration, SSE for web clients
## Prerequisites
- Node.js 16+
- Python 3.6+
- The JobSpy tool installed and available
## Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/jobspy-mcp-server.git
cd jobspy-mcp-server
# Install dependencies
npm install
# Make sure the JobSpy tool is properly set up
cd ../jobSpy
pip install -r requirements.txt
chmod +x run.sh
```
## Configuration
The server will automatically try to locate the JobSpy script in standard locations:
- `../jobSpy/run.sh` (relative to the server directory)
- `./run.sh` (in the current directory)
- `/app/run.sh` (for Docker environments)
### Environment Variables
You can configure the server using the following environment variables:
| Environment Variable | Description | Default |
|-------------------------|------------------------------------------|-------------|
| `JOBSPY_DOCKER_IMAGE` | Docker image to use for JobSpy | `jobspy` |
| `JOBSPY_ACCESS_TOKEN` | Access token for JobSpy API (if required)| none |
| `PORT` | Port for the MCP server | `9423` |
| `HOST` | Host for HTTP server | '0.0.0.0' |
| `ENABLE_SSE` | Enable Server-Sent Events transport | 0 |
## Setting Up Configuration
You can set these configuration values in multiple ways:
### 1. Using environment variables directly
```bash
export JOBSPY_DOCKER_IMAGE=jobspy
export JOBSPY_HOST='0.0.0.0'
export JOBSPY_PORT=9423
export ENABLE_SSE=1
```
### 2. Using a .env file
Create a `.env` file in the root directory with your configuration:
```
JOBSPY_DOCKER_IMAGE=jobspy
JOBSPY_HOST='0.0.0.0'
JOBSPY_PORT=9423
ENABLE_SSE=1
```
## Usage
### Starting the server
```bash
npm start
```
### Connecting with Claude Desktop
Add the following to your Claude Desktop config file (typically at `~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"jobspy": {
"command": "node",
"args": ["/path/to/jobspy-mcp-server/src/index.js"],
"env": {
"ENABLE_SSE": 0
}
}
}
}
```
### Using with Web Clients (SSE Transport)
The server exposes HTTP endpoints that allow web applications to interact with the JobSpy MCP server:
- **Connect for updates**: `GET /mcp/connect`
- Establishes a Server-Sent Events (SSE) connection for real-time updates
- Returns progress updates and job search results
- **Send requests**: `POST /mcp/request`
- Accepts tool invocation requests in MCP format
- Returns tool responses
Example JavaScript client for browser:
```javascript
// Connect to SSE endpoint
const eventSource = new EventSource('http://localhost:9423/mcp/connect');
// Listen for updates
eventSource.onmessage = function(event) {
const data = JSON.parse(event.data);
console.log('Received update:', data);
// Handle progress updates
if (data.type === 'progress') {
updateProgressBar(data.progress);
}
};
// Send a search request
async function searchJobs() {
const response = await fetch('http://localhost:9423/mcp/request', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
tool: 'search_jobs',
params: {
search_term: 'software engineer',
location: 'San Francisco, CA',
site_names: 'indeed,linkedin'
}
})
});
return await response.json();
}
```
### API Usage
The server exposes the following endpoints:
#### Search Jobs
```
GET /search
```
Query parameters:
- `site_names`: Comma-separated list of job sites to search
- `search_term`: Term to search for
- `location`: Job location
- And other JobSpy parameters as needed
### Available Tools
#### search_jobs
Searches for jobs across various job listing websites.
**Parameters:**
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| site_names | string | Comma-separated list of job sites to search (indeed,linkedin,zip_recruiter,glassdoor,google,bayt,naukri) | "indeed" |
| search_term | string | Search term for jobs | "software engineer" |
| location | string | Location for job search | "San Francisco, CA" |
| google_search_term | string | Google specific search term | null |
| results_wanted | integer | Number of results wanted | 20 |
| hours_old | integer | How many hours old the jobs can be | 72 |
| country_indeed | string | Country for Indeed search | "USA" |
| linkedin_fetch_description | boolean | Whether to fetch LinkedIn job descriptions (slower) | false |
| format | string | Output format (json or csv) | "json" |
| output | string | Output filename without extension | "jobs" |
**Example usage with Claude:**
```
I need to find senior software engineer jobs in Boston posted in the last 24 hours on both LinkedIn and Indeed.
```
## Docker Support
A Dockerfile is provided to containerize the MCP server:
```bash
# Build the Docker image
docker build -t jobspy-mcp-server .
# Run the container
docker run -p 9423:9423 jobspy-mcp-server
```
## Development
### Running in development mode
```bash
npm run dev
```
### Running tests
```bash
npm test
```
```bash
curl -X POST "http://localhost:9423/api" \
-H "Content-Type: application/json" \
-d '{
"method": "search_jobs",
"params": {
"search_term": "software engineer",
"location": "San Francisco, CA",
"site_names": "indeed,linkedin",
"results_wanted": 10,
"format": "json"
}
}'
```
## License
MIT
