Skip to content
Back to search

jobspy-mcp-server

MCP server to search for jobs across multiple job listing platforms

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/borgius--jobspy-mcp-server/badge.svg)](/listings/borgius--jobspy-mcp-server)

HTML

<a href="/listings/borgius--jobspy-mcp-server"><img src="/api/listings/borgius--jobspy-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 240 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # JobSpy MCP Server
  2. 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/Bunsly/JobSpy) tool.
  3. ## Features
  4. - Search for jobs across multiple platforms (Indeed, LinkedIn, Glassdoor, etc.)
  5. - Filter by search terms, location, time frames, and more
  6. - Get structured job data that AI models can easily process
  7. - Format results as JSON or CSV
  8. - Multiple transport options: stdio for Claude integration, SSE for web clients
  9. ## Prerequisites
  10. - Node.js 16+
  11. - Python 3.6+
  12. - The JobSpy tool installed and available
  13. ## Installation
  14. ```bash
  15. # Clone the repository
  16. git clone https://github.com/borgius/jobspy-mcp-server.git
  17. cd jobspy-mcp-server
  18. # Install dependencies
  19. npm install
  20. # Make sure the JobSpy tool is properly set up
  21. cd ../jobSpy
  22. pip install -r requirements.txt
  23. chmod +x run.sh
  24. ```
  25. ## Configuration
  26. The server will automatically try to locate the JobSpy script in standard locations:
  27. - `../jobSpy/run.sh` (relative to the server directory)
  28. - `./run.sh` (in the current directory)
  29. - `/app/run.sh` (for Docker environments)
  30. ### Environment Variables
  31. You can configure the server using the following environment variables:
  32. | Environment Variable | Description | Default |
  33. |-------------------------|------------------------------------------|-------------|
  34. | `JOBSPY_DOCKER_IMAGE` | Docker image to use for JobSpy | `jobspy` |
  35. | `JOBSPY_ACCESS_TOKEN` | Access token for JobSpy API (if required)| none |
  36. | `PORT` | Port for the MCP server | `9423` |
  37. | `HOST` | Host for HTTP server | '0.0.0.0' |
  38. | `ENABLE_SSE` | Enable Server-Sent Events transport | 0 |
  39. ## Setting Up Configuration
  40. You can set these configuration values in multiple ways:
  41. ### 1. Using environment variables directly
  42. ```bash
  43. export JOBSPY_DOCKER_IMAGE=jobspy
  44. export JOBSPY_HOST='0.0.0.0'
  45. export JOBSPY_PORT=9423
  46. export ENABLE_SSE=1
  47. ```
  48. ### 2. Using a .env file
  49. Create a `.env` file in the root directory with your configuration:
  50. ```
  51. JOBSPY_DOCKER_IMAGE=jobspy
  52. JOBSPY_HOST='0.0.0.0'
  53. JOBSPY_PORT=9423
  54. ENABLE_SSE=1
  55. ```
  56. ## Usage
  57. ### Starting the server
  58. ```bash
  59. npm start
  60. ```
  61. ### Connecting with Claude Desktop
  62. Add the following to your Claude Desktop config file (typically at `~/Library/Application Support/Claude/claude_desktop_config.json`):
  63. ```json
  64. {
  65. "mcpServers": {
  66. "jobspy": {
  67. "command": "node",
  68. "args": ["/path/to/jobspy-mcp-server/src/index.js"],
  69. "env": {
  70. "ENABLE_SSE": 0
  71. }
  72. }
  73. }
  74. }
  75. ```
  76. ### Using with Web Clients (SSE Transport)
  77. The server exposes HTTP endpoints that allow web applications to interact with the JobSpy MCP server:
  78. - **Connect for updates**: `GET /mcp/connect`
  79. - Establishes a Server-Sent Events (SSE) connection for real-time updates
  80. - Returns progress updates and job search results
  81. - **Send requests**: `POST /mcp/request`
  82. - Accepts tool invocation requests in MCP format
  83. - Returns tool responses
  84. Example JavaScript client for browser:
  85. ```javascript
  86. // Connect to SSE endpoint
  87. const eventSource = new EventSource('http://localhost:9423/mcp/connect');
  88. // Listen for updates
  89. eventSource.onmessage = function(event) {
  90. const data = JSON.parse(event.data);
  91. console.log('Received update:', data);
  92. // Handle progress updates
  93. if (data.type === 'progress') {
  94. updateProgressBar(data.progress);
  95. }
  96. };
  97. // Send a search request
  98. async function searchJobs() {
  99. const response = await fetch('http://localhost:9423/mcp/request', {
  100. method: 'POST',
  101. headers: {
  102. 'Content-Type': 'application/json'
  103. },
  104. body: JSON.stringify({
  105. tool: 'search_jobs',
  106. params: {
  107. search_term: 'software engineer',
  108. location: 'San Francisco, CA',
  109. site_names: 'indeed,linkedin'
  110. }
  111. })
  112. });
  113. return await response.json();
  114. }
  115. ```
  116. ### API Usage
  117. The server exposes the following endpoints:
  118. #### Search Jobs
  119. ```
  120. GET /search
  121. ```
  122. Query parameters:
  123. - `site_names`: Comma-separated list of job sites to search
  124. - `search_term`: Term to search for
  125. - `location`: Job location
  126. - And other JobSpy parameters as needed
  127. ### Available Tools
  128. #### search_jobs
  129. Searches for jobs across various job listing websites.
  130. **Parameters:**
  131. | Parameter | Type | Description | Default |
  132. |-----------|------|-------------|---------|
  133. | site_names | string | Comma-separated list of job sites to search (indeed,linkedin,zip_recruiter,glassdoor,google,bayt,naukri) | "indeed" |
  134. | search_term | string | Search term for jobs | "software engineer" |
  135. | location | string | Location for job search | "San Francisco, CA" |
  136. | google_search_term | string | Google specific search term | null |
  137. | results_wanted | integer | Number of results wanted | 20 |
  138. | hours_old | integer | How many hours old the jobs can be | 72 |
  139. | country_indeed | string | Country for Indeed search | "USA" |
  140. | linkedin_fetch_description | boolean | Whether to fetch LinkedIn job descriptions (slower) | false |
  141. | format | string | Output format (json or csv) | "json" |
  142. | output | string | Output filename without extension | "jobs" |
  143. **Example usage with Claude:**
  144. ```
  145. I need to find senior software engineer jobs in Boston posted in the last 24 hours on both LinkedIn and Indeed.
  146. ```
  147. ## Docker Support
  148. A Dockerfile is provided to containerize the MCP server:
  149. ```bash
  150. # Build the Docker image
  151. docker build -t jobspy-mcp-server .
  152. # Run the container
  153. docker run -p 9423:9423 jobspy-mcp-server
  154. ```
  155. ## Development
  156. ### Running in development mode
  157. ```bash
  158. npm run dev
  159. ```
  160. ### Running tests
  161. ```bash
  162. npm test
  163. ```
  164. ```bash
  165. curl -X POST "http://localhost:9423/api" \
  166. -H "Content-Type: application/json" \
  167. -d '{
  168. "method": "search_jobs",
  169. "params": {
  170. "search_term": "software engineer",
  171. "location": "San Francisco, CA",
  172. "site_names": "indeed,linkedin",
  173. "results_wanted": 10,
  174. "format": "json"
  175. }
  176. }'
  177. ```
  178. ## License
  179. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.