home / mcp / mcp jobs server

MCP Jobs Server

Provides zero-setup, multi-source job postings search and normalization via MCP, with optional advanced crawling controls.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "mergedao-mcp-jobs": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-jobs"
      ],
      "env": {
        "PASSWORD": "secret",
        "USERNAME": "user1",
        "MCP_API_KEY": "YOUR_API_KEY",
        "CRAWLER_DEBUG": "false",
        "CRAWLER_TIMEOUT": "30000",
        "CRAWLER_HEADLESS": "true",
        "CRAWLER_VIEWPORT_WIDTH": "1280",
        "CRAWLER_VIEWPORT_HEIGHT": "800"
      }
    }
  }
}

You can run MCP Jobs as a zero-setup, multi-platform job postings aggregator. It sings with MCP architecture to fetch listings from major job sites, standardize the output, and serve them to your AI assistants or workflows with no mandatory configuration. This makes it easy to ask natural-language questions like “show me frontend roles in Shanghai” and get structured, up-to-date results across multiple sources.

How to use

Start the service with a single, zero-configuration command and interact with it through your MCP client or AI assistant. You can search for jobs, view details, and compare data across platforms using natural language.

Typical usage patterns include: - Searching for jobs by title, city, or salary range - Retrieving detailed information for a specific job - Aggregating data from multiple sources for unified results - Analyzing salary trends or popular skills across regions

How to install

Prerequisites you need to have installed on your system:
- Node.js (version 16 or newer)
- npm (comes with Node.js) or an alternative like yarn or pnpm

Step-by-step run flow for immediate use:
```bash
npx -y mcp-jobs
```
This starts the MCP Jobs service with zero configuration. You can then proceed to connect an MCP client or AI assistant to begin querying for job listings.

If you prefer a local installation for frequent use, you have two additional options shown in examples:
- Global install and run:
  - `npm install -g mcp-jobs`
  - `mcp-jobs`
- Project-local install:
  - `npm install mcp-jobs`  or `yarn add mcp-jobs` or `pnpm add mcp-jobs

Additional configuration and notes

All core features work without any configuration. Advanced options exist to customize crawling and security, but they are optional.

Optional configuration you may apply later includes: - Basic authentication (USERNAME, PASSWORD) - Crawler settings such as headless mode, timeouts, viewport size, and debugging flags - Optional MCP API key to unlock extra features

Security and usage notes

- This service is designed to be zero-setup and easy to use, but you should respect each job site’s terms of service and rate limits. - The zero-configuration mode is intended for quick starts; enable optional authentication and API keys only if you need elevated capabilities.

Troubleshooting and debugging

If you run into issues while crawling or connecting, you can enable debugging and adjust crawler settings to reproduce and diagnose problems:
```bash
CRAWLER_HEADLESS=false npx -y mcp-jobs
CRAWLER_DEBUG=true npx -y mcp-jobs
```
You can also tune browser behavior and timeouts using optional environment variables like `CRAWLER_VIEWPORT_WIDTH`, `CRAWLER_VIEWPORT_HEIGHT`, and `CRAWLER_TIMEOUT`.

Available tools

searchJobs

Query jobs by title, location, salary and other filters across multiple platforms.

getJobDetails

Fetch detailed information for a specific job listing.

aggregateSources

Aggregate and normalize data from several job sites into a consistent format.

realTimeUpdates

Provide up-to-date job postings with automatic refreshes where supported.

analyzeMarkets

Perform comparisons across cities or roles to identify market trends.