Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/borgius/jobspy-js/llms.txt

Use this file to discover all available pages before exploring further.

JobSpy JS includes a built-in MCP (Model Context Protocol) server that exposes job scraping tools to AI agents like Claude Desktop. This allows you to search for jobs and fetch job details directly from your AI assistant.

​
What is MCP?

The Model Context Protocol is an open standard that enables AI assistants to connect to external data sources and tools. JobSpy’s MCP server exposes two tools:
  • scrape_jobs — Search for jobs across multiple job boards
  • fetch_job — Get full details for a specific job by ID

​
Prerequisites

  • Node.js 18+ installed
  • Claude Desktop or another MCP-compatible client
  • JobSpy JS installed globally or locally (npm install -g jobspy-js or npm install jobspy-js)
For Google Jobs scraping, you must also install Playwright’s Chromium browser:
npx playwright install chromium

​
Installation

1
Install JobSpy JS
2
Install the package globally to make it available to your MCP client:
3
npm install -g jobspy-js
4
Or install it locally in your project:
5
npm install jobspy-js
6
Locate your MCP client config
7
For Claude Desktop, the configuration file is located at:
8
macOS
~/Library/Application Support/Claude/claude_desktop_config.json
Windows
%APPDATA%\Claude\claude_desktop_config.json
Linux
~/.config/Claude/claude_desktop_config.json
9
If the file doesn’t exist, create it.
10
Add JobSpy to your MCP config
11
Add the following to your claude_desktop_config.json:
12
Global Installation
{
  "mcpServers": {
    "jobspy": {
      "command": "npx",
      "args": ["-y", "jobspy-js", "--mcp"]
    }
  }
}
Local Installation
{
  "mcpServers": {
    "jobspy": {
      "command": "node",
      "args": ["/absolute/path/to/node_modules/.bin/jobspy", "--mcp"]
    }
  }
}
With Environment Variables
{
  "mcpServers": {
    "jobspy": {
      "command": "npx",
      "args": ["-y", "jobspy-js", "--mcp"],
      "env": {
        "LINKEDIN_USERNAME": "your-email@example.com",
        "LINKEDIN_PASSWORD": "your-password",
        "JOBSPY_CREDS": "1"
      }
    }
  }
}
13
The npx -y jobspy-js --mcp approach automatically uses the latest version or installs it if not present. For production use, consider pinning to a specific version.
14
Restart your MCP client
15
For Claude Desktop:
16
  • Quit Claude Desktop completely
  • Reopen the application
  • The JobSpy MCP server will start automatically
    • 17
    Verify the connection
    18
    In Claude Desktop, you should see a small hammer icon (🔨) or tool indicator when JobSpy tools are available. Try asking:
    19
    Find me 10 software engineer jobs in San Francisco
    20
    Claude should recognize the request and offer to use the scrape_jobs tool.

    ​
    Configuration Options

    ​
    Proxy Support

    If you need to route requests through a proxy, set the proxy in environment variables: 
    {
  "mcpServers": {
    "jobspy": {
      "command": "npx",
      "args": ["-y", "jobspy-js", "--mcp"],
      "env": {
        "HTTP_PROXY": "http://user:pass@proxy.example.com:8080",
        "HTTPS_PROXY": "http://user:pass@proxy.example.com:8080"
      }
    }
  }
}

    ​
    Authentication Credentials

    Some job boards (especially LinkedIn) may require authentication for reliable scraping. Set credentials via environment variables: 
    {
  "mcpServers": {
    "jobspy": {
      "command": "npx",
      "args": ["-y", "jobspy-js", "--mcp"],
      "env": {
        "JOBSPY_CREDS": "1",
        "LINKEDIN_USERNAME": "your-email@example.com",
        "LINKEDIN_PASSWORD": "your-password",
        "INDEED_USERNAME": "your-indeed-email@example.com",
        "INDEED_PASSWORD": "your-indeed-password"
      }
    }
  }
}
    Never commit configuration files containing credentials to version control. Use environment-specific configs or secret management tools.
    Supported credential environment variables:
    • LINKEDIN_USERNAME / LINKEDIN_PASSWORD
    • INDEED_USERNAME / INDEED_PASSWORD
    • GLASSDOOR_USERNAME / GLASSDOOR_PASSWORD
    • ZIPRECRUITER_USERNAME / ZIPRECRUITER_PASSWORD
    • BAYT_USERNAME / BAYT_PASSWORD
    • NAUKRI_USERNAME / NAUKRI_PASSWORD
    • BDJOBS_USERNAME / BDJOBS_PASSWORD
    Credentials are only used when JOBSPY_CREDS=1 is set.

    ​
    Troubleshooting

    1. Verify the config file path is correct
    2. Check that the JSON syntax is valid (no trailing commas, proper quotes)
    3. Ensure Node.js is in your system PATH
    4. Try restarting Claude Desktop completely (quit and reopen)
    5. Check Claude Desktop logs (Help → View Logs)
    If using a local installation, provide the absolute path to the executable:
    {
  "mcpServers": {
    "jobspy": {
      "command": "node",
      "args": ["/Users/yourname/project/node_modules/.bin/jobspy", "--mcp"]
    }
  }
}
    Google Jobs requires Playwright’s Chromium browser. Install it with:
    npx playwright install chromium
    Google also requires a clean residential IP or high-quality proxy. Datacenter IPs are often blocked.
    LinkedIn frequently rate-limits anonymous scraping. Try:
    1. Adding credentials via environment variables
    2. Using a residential proxy
    3. Reducing results_wanted to a smaller number (10-20)
    4. Enabling credential fallback with JOBSPY_CREDS=1

    ​
    Next Steps

    Usage Examples

    Learn how to use JobSpy tools with Claude Desktop

    SDK Reference

    Explore all available parameters and options

    Build docs developers (and LLMs) love

    Get started for freeTalk to us