mcp-jobs

🚀 Zero-configuration multi-platform job aggregation service! Based on the MCP architecture, it supports fetching job information from major recruitment websites. Ready to use out of the box, no setup required.

⚡ 30-Second Quick Start

🚀 Step 1: Start the Service (Zero Configuration)

bash

One command to start immediately

npx -y mcp-jobs

🤖 Step 2: Configure AI Client

Add the following in your AI client (e.g., Cursor, Claude Desktop):

• Service Name: mcp-jobs
• Command: npx -y mcp-jobs
• Environment Variables: Leave blank

💬 Step 3: Start Using

Simply tell your AI assistant: "Search for front-end development jobs in Beijing"

That's it! 🎉 No registration, no API Key, no configuration files.

🌟 Core Features

• 🔓 Zero Barrier to Entry: No API Key, no registration, no configuration
• 📦 Ready to Use Out of the Box: One command to start the full service
• 🔍 Intelligent Search: Supports filtering by job title, city, salary range, etc.
• 🌐 Multi-Platform Aggregation: Automatically fetches data from multiple major recruitment websites
• 📊 Standardized Output: Unified data format, easy for large models to process
• ⚡ Real-Time Updates: Ensures the timeliness of job information
• 🔧 Optional Enhancements: Supports unlocking additional features with an API Key (completely optional)

📦 Installation Methods

🚀 Instant Run (Recommended)

No installation, no configuration, ready to use immediately:

bash

One command to start immediately

npx -y mcp-jobs

🔧 Global Installation (Optional)

If you need to use it frequently:

bash

Global installation

npm install -g mcp-jobs

Directly run

mcp-jobs

📁 Project Installation (Optional)

bash

Install as a project dependency

npm install mcp-jobs

or using yarn

yarn add mcp-jobs

or using pnpm

pnpm add mcp-jobs

🎯 Usage Instructions

🚀 Basic Usage (Zero Configuration)

No setup required, start immediately:

bash

Start the service

npx -y mcp-jobs

The service will automatically provide the following features:

✅ Job search

✅ Job detail retrieval

✅ Multi-platform data aggregation

✅ Standardized data output

It's that simple!

🔧 Advanced Configuration (Completely Optional)

If you need additional enhanced features, you can optionally configure the following parameters:

bash

Optional: Copy the configuration template

cp .env.example .env

Optional: Edit the configuration file, uncomment the features you need

USERNAME=your_username # Optional: Basic authentication

PASSWORD=your_password # Optional: Basic authentication

Optional: Crawler configuration

CRAWLER_HEADLESS=true # Optional: Headless mode (set to false for debugging)

CRAWLER_TIMEOUT=30000 # Optional: Page timeout (milliseconds)

CRAWLER_VIEWPORT_WIDTH=1280 # Optional: Browser viewport width

CRAWLER_VIEWPORT_HEIGHT=800 # Optional: Browser viewport height

CRAWLER_DEBUG=false # Optional: Debug mode

Optional Configuration Explanation

Configuration Item	Purpose	Required
USERNAME	Basic authentication username	❌ Optional
PASSWORD	Basic authentication password	❌ Optional
CRAWLER_HEADLESS	Browser headless mode (true/false)	❌ Optional
CRAWLER_TIMEOUT	Page timeout (milliseconds)	❌ Optional
CRAWLER_VIEWPORT_WIDTH	Browser viewport width	❌ Optional
CRAWLER_VIEWPORT_HEIGHT	Browser viewport height	❌ Optional
CRAWLER_DEBUG	Debug mode (true/false)	❌ Optional

💡 Important Note: All configurations are completely optional. The service provides full core functionality without any configuration.

🤖 AI Client Configuration

🚀 Cursor Configuration (Zero Configuration)

Minimal Configuration (Recommended)

1. Open Cursor settings
2. Go to Features > MCP Servers
3. Click "+ Add New MCP Server"
4. Enter the following information:
   • Name: mcp-jobs
   • Type: command
   • Command: npx -y mcp-jobs

JSON Configuration Method

Basic Configuration (Ready to Use Out of the Box):

json
{
"mcpServers": {
"mcp-jobs": {
"command": "npx",
"args": ["-y", "mcp-jobs"]
}
}
}Advanced Configuration (Optional Enhancements):

json
{
"mcpServers": {
"mcp-jobs": {
"command": "npx",
"args": ["-y", "mcp-jobs"],
"env": {
"USERNAME": "your-username",
"PASSWORD": "your-password"
}
}
}
}

💡 Tip: It is recommended to use the basic configuration, as it already provides full job search functionality!

🤖 Claude Desktop Configuration

Zero-configuration Setup:

1. Open Claude Desktop
2. Click on the Settings icon in the lower left corner
3. Select the "MCP Servers" option
4. Click "Add New Server"
5. Enter the following information:
   • Name: mcp-jobs
   • Type: command
   • Command: npx -y mcp-jobs
   • Environment Variables: Leave blank (no variables needed)

That's it! No API Key required, ready to use immediately.

🚀 Windsurf Configuration

Basic Configuration (Zero-setup):

json
{
"mcpServers": {
"mcp-jobs": {
"command": "npx",
"args": ["-y", "mcp-jobs"]
}
}
}

🚀 Cline Configuration

Basic Configuration (Zero-setup):

yaml
mcp:
servers:
mcp-jobs:
command: npx
args: ["-y", "mcp-jobs"]

🔧 Advanced Configuration (Fully Optional)

⚠️ Important Note: All of the following configurations are completely optional! The service can provide full functionality without any configuration.

If you need to customize the service behavior, you can optionally configure the following environment variables:

bash

Optional: MCP API key (for unlocking advanced features)

Optional: Basic authentication

USERNAME=your-username

PASSWORD=your-password

Optional: Custom MCP service address

💡 Reminder: Full job search functionality is available without any configuration!

🎯 Get Started Immediately

After configuration (just one line of command!), you can describe your job search needs to the AI assistant using natural language:

💬 Usage Examples

Direct Job Search:

• "Search for front-end developer positions in Shanghai"
• "Find data analyst jobs in Beijing with more than 3 years of experience"
• "Identify the highest-paying product manager positions in Hangzhou"

Get Job Details:

• "Get detailed information about this position: [job link]"
• "Analyze the requirements and salary for this position"

Smart Analysis:

• "Compare the salary levels of similar positions in different cities"
• "Summarize the current market's popular skill requirements"

🚀 Zero-barrier Experience: No need to learn complex API calls, just use natural language to get professional job search services!

The large model will automatically call the mcp-jobs service to fetch relevant information and display the results for you.

🔧 Debugging and Development

🐛 Debug Mode

If you need to debug crawler behavior or develop new features, you can enable debug mode:

bash

Enable visible browser window (non-headless mode)

CRAWLER_HEADLESS=false npx -y mcp-jobs

Enable debug logging

CRAWLER_DEBUG=true npx -y mcp-jobs

Combined usage

CRAWLER_HEADLESS=false CRAWLER_DEBUG=true npx -y mcp-jobs

⚙️ Custom Browser Configuration

bash

Customize viewport size

CRAWLER_VIEWPORT_WIDTH=1920 CRAWLER_VIEWPORT_HEIGHT=1080 npx -y mcp-jobs

Increase timeout (useful for slow networks)

CRAWLER_TIMEOUT=60000 npx -y mcp-jobs

Customize user agent

CRAWLER_USER_AGENT="Custom Bot 1.0" npx -y mcp-jobs

📝 Configuration Priority

The priority of configurations from high to low:

1. Site-specific Configuration - browserConfig set for specific websites in crawlerConfig.ts
2. Environment Variables - Set via CRAWLER_* environment variables
3. Default Configuration - System defaults

🌟 Why Choose MCP Jobs?

✅ Truly Zero-barrier

• 🚫 No Account Registration - No need to fill out any personal information
• 🚫 No Complex Configuration - Start with a single command
• 🚫 No Documentation Learning - Interact directly with natural language

⌛ Ready to Use

• 📦 Out-of-the-box, no preparation needed
• 🔍 Full job search functionality
• 🌐 Multi-platform data aggregation
• 📊 Standardized data output

🛡️ Reliable and Stable

• 🔄 Automatic retry mechanism
• ⚠️ Graceful error handling
• 📈 Real-time data updates
• 🔧 Optional advanced features

📋 Important Notes1. Completely Free - Core features are available at no cost

1. Compliance with Regulations - Please adhere to the usage agreements of each job platform
2. Reasonable Use - It is recommended to control the request frequency to avoid excessive access
3. System Requirements - Node.js >= 16.0.0

Open Source License

MIT License

Getting Help

If you encounter any issues while using this, please get help through the following methods:

• Submit a GitHub Issue