borgius/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 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/borgius/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 |
| JOBSPYDOCKERIMAGE | Docker image to use for JobSpy | jobspy |
| JOBSPYACCESSTOKEN | Access token for JobSpy API (if required)| none |
| PORT | Port for the MCP server | 9423 |
| HOST | Host for HTTP server | '0.0.0.0' |
| ENABLESSE | 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 JOBSPYDOCKERIMAGE=jobspy
export JOBSPYHOST='0.0.0.0'
export JOBSPYPORT=9423
export ENABLESSE=1
### 2. Using a .env file
Create a .env file in the root directory with your configuration:
JOBSPYDOCKERIMAGE=jobspy
JOBSPYHOST='0.0.0.0'
JOBSPYPORT=9423
ENABLESSE=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/claudedesktopconfig.json):
json
"mcpServers": {
"jobspy": {
"command": "node",
"args": ["/path/to/jobspy-mcp-server/src/index.js"],
"env": {
"ENABLESSE": 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', {