Skip to main content
Glama
amitt007

JobSpy MCP Server

by amitt007
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

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

Related MCP server: JobSpy MCP Server

Prerequisites

  • Node.js 16+

  • Python 3.6+

  • The JobSpy tool installed and available

Installation

# 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

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

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

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):

{
  "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:

// 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:

# 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

npm run dev

Running tests

npm test
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

Available Tools

1 tool
search_jobsC

Search for jobs across various job listing websites

ParametersJSON Schema
NameRequiredDescriptionDefault
caCertNoPath to CA Certificate file for proxies
formatNoOutput formatjson
offsetNoStarts the search from an offset
jobTypeNoType of job
proxiesNo
timeoutNoTimeout in milliseconds for the job search process
verboseNoControls verbosity (0=errors only, 1=errors+warnings, 2=all logs)
distanceNoDistance in miles
hoursOldNoHow many hours old the jobs can be
isRemoteNoWhether to search for remote jobs only. Accepts any truthy value.
locationNoLocation for job searchremote
easyApplyNoFilter for jobs that are hosted on the job board site
siteNamesNoindeed
searchTermNoSearch term for jobssoftware engineer
countryIndeedNoCountry for Indeed searchUSA
resultsWantedNoNumber of results wanted
googleSearchTermNoGoogle specific search term
descriptionFormatNoFormat type of the job descriptionsmarkdown
linkedinCompanyIdsNo
enforceAnnualSalaryNoConverts wages to annual salary
linkedinFetchDescriptionNoWhether to fetch LinkedIn job descriptions (slower). Accepts any truthy value.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Search for jobs across various job listing websites,' but does not mention that the tool performs live network requests to third-party sites, may require proxies/timeout settings, or could be slow. Key behavioral traits such as output format, mutation potential, and side effects are absent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words and is front-loaded. However, it is perhaps too terse for a tool with 21 parameters, though that shortfall is more a completeness issue than a conciseness one.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 21 parameters, no output schema, and no annotations, placing a heavy burden on the description to explain what the search returns, how results are structured, and what sites are covered. The description only says 'Search for jobs across various job listing websites' and does not address return value shape, default behaviors, or operational constraints, leaving significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 86% (well above 80%), so the baseline is 3 even without param detail in the description. The one-line description adds no parameter-specific meaning, but the schema already documents most parameters well, and the description does not actively mislead.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Search') and a clear resource ('jobs across various job listing websites'), making the core action understandable. However, it does not differentiate from any sibling tools (none are listed), so it falls short of a perfect score for distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, no context about typical use cases, and no exclusions. It simply states the broad function, leaving the agent to infer when it is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.0.0
    • First observedsearch_jobs
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 1 tool

Disambiguation5/5

There is only one tool, so an agent cannot confuse it with another tool. The name and description clearly indicate a single, dedicated job search action.

Naming Consistency4/5

The sole tool uses a clear snake_case verb_noun format (search_jobs) that matches common MCP conventions. With only one tool there is no full pattern to assess, but no inconsistency is present.

Tool Count3/5

A single tool covering job search across multiple sites is functional, but the server feels minimal and offers no supporting operations. It sits at the borderline of being too few tools for a general job-search domain.

Completeness3/5

The tool covers centralized searching across job listing websites, which satisfies the basic stated purpose. However, there are no tools for inspecting individual job details, refining saved searches, or acting on results, leaving notable gaps for a wider job-search workflow.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • JobSpy MCP Server by borgius

    JobSpy MCP Serverofficial

    borgius
    F
    license
    Not graded
    quality
    F
    maintenance
    Enables AI assistants to search for jobs across multiple platforms (Indeed, LinkedIn, Glassdoor, etc.) using the JobSpy tool, with filtering and structured output.
    114
    -

  • JobSpy MCP Server

    chinpeerapat
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables job search and scraping across multiple job boards (LinkedIn, Indeed, Glassdoor, etc.) with advanced filtering, directly from Claude Desktop or other MCP clients.
    5
    MIT

  • LinkedIn Job Scraper MCP

    Anjani27
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to search, filter, and extract job listings from LinkedIn using an automated headless browser with semantic AI filtering and deduplication.
    7 npm
    MIT

  • JobSpy Cowork MCP Server

    m0408-dev
    F
    license
    Not graded
    quality
    B
    maintenance
    Enables searching real job listings from multiple job boards (Indeed, LinkedIn, Glassdoor, Google Jobs, etc.) through a single MCP tool, designed for use as a custom connector in Claude Cowork.
    -