mcp-jobs

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

⚡ 30-Second Quick Start

🚀 Step 1: Start the Service (Zero Configuration)

# 一行命令，立即启动
npx -y mcp-jobs

🤖 Step 2: Configure Your AI Client

Add the following to your AI client (such as Cursor, Claude Desktop):

• Service Name: mcp-jobs

• Command: npx -y mcp-jobs

• Environment Variables: Leave empty

💬 Step 3: Start Using It

Simply tell your AI assistant: "Search for frontend developer jobs in Beijing"

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

Related MCP server: JobSpy MCP Server

🌟 Core Features

• 🔓 Zero Barrier: No API Key, no registration, no configuration

• 📦 Out of the Box: Start the full service with a single command

• 🔍 Smart Search: Filter by job title, city, salary range, and more

• 🌐 Multi-Platform Aggregation: Automatically fetches data from multiple major job boards

• 📊 Standardized Output: Unified data format, easy for LLMs to process

• ⚡ Real-Time Updates: Ensures job information stays current

• 🔧 Optional Enhancements: API Key support to unlock extra features (fully optional)

📦 Installation Methods

🚀 Run Instantly (Recommended)

No installation, no configuration, use immediately:

# 一行命令，立即启动
npx -y mcp-jobs

🔧 Global Installation (Optional)

If you need to use it frequently:

# 全局安装
npm install -g mcp-jobs

# 直接运行
mcp-jobs

📁 Project-Level Installation (Optional)

# 安装到项目依赖中
npm install mcp-jobs
# 或使用 yarn
yarn add mcp-jobs
# 或使用 pnpm
pnpm add mcp-jobs

🎯 Usage Guide

🚀 Basic Usage (Zero Configuration)

No setup required, start right away:

# 启动服务
npx -y mcp-jobs

# 服务将自动提供以下功能：
# ✅ 职位搜索
# ✅ 职位详情获取
# ✅ 多平台数据聚合
# ✅ 标准化数据输出

It's that simple!

🔧 Advanced Configuration (Fully Optional)

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

# 可选：复制配置模板
cp .env.example .env

# 可选：编辑配置文件，取消注释您需要的功能
# USERNAME=your_username            # 可选：基础认证
# PASSWORD=your_password            # 可选：基础认证

# 可选：爬虫配置
# CRAWLER_HEADLESS=true             # 可选：无头模式 (调试时可设为 false)
# CRAWLER_TIMEOUT=30000             # 可选：页面超时时间 (毫秒)
# CRAWLER_VIEWPORT_WIDTH=1280       # 可选：浏览器视窗宽度
# CRAWLER_VIEWPORT_HEIGHT=800       # 可选：浏览器视窗高度
# CRAWLER_DEBUG=false               # 可选：调试模式

Optional Configuration Reference

💡 Important Note: All configuration is fully optional. The service provides complete 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 (Out of the Box):

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

Advanced Configuration (Optional Enhancements):

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

💡 Tip: The basic configuration is recommended and already provides full job search functionality!

🤖 Claude Desktop Configuration

Zero-Configuration Setup:

1. Open Claude Desktop

2. Click the Settings icon in the bottom-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 empty (no variables needed)

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

🚀 Windsurf Configuration

Basic Configuration (Zero Setup):

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

🚀 Cline Configuration

Basic Configuration (Zero Setup):

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

🔧 Advanced Configuration (Fully Optional)

⚠️ Important Note: All of the following configuration is fully optional! The service provides complete functionality without any configuration.

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

# 可选：MCP API 密钥（用于解锁高级功能）
# 可选：基础认证
# USERNAME=your-username
# PASSWORD=your-password

# 可选：自定义 MCP 服务地址

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

🎯 Start Using It Now

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

💬 Usage Examples

Search for jobs directly:

• "Search for frontend developer positions in Shanghai"

• "Find data analyst roles in Beijing, requiring 3+ years of experience"

• "Find the highest-paying product manager positions in Hangzhou"

Get job details:

• "Get the detailed information for this job: [job link]"

• "Analyze the requirements and salary for this position"

Smart analysis:

• "Compare salary levels for similar jobs across different cities"

• "Summarize the in-demand skills in the current market"

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

The LLM 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:

# 启用可视化浏览器窗口（非无头模式）
CRAWLER_HEADLESS=false npx -y mcp-jobs

# 启用调试日志
CRAWLER_DEBUG=true npx -y mcp-jobs

# 组合使用
CRAWLER_HEADLESS=false CRAWLER_DEBUG=true npx -y mcp-jobs

⚙️ Custom Browser Configuration

# 自定义视窗大小
CRAWLER_VIEWPORT_WIDTH=1920 CRAWLER_VIEWPORT_HEIGHT=1080 npx -y mcp-jobs

# 增加超时时间（适用于慢速网络）
CRAWLER_TIMEOUT=60000 npx -y mcp-jobs

# 自定义用户代理
CRAWLER_USER_AGENT="Custom Bot 1.0" npx -y mcp-jobs

📝 Configuration Priority

Configuration priority, from highest to lowest:

1. Site-Specific Configuration - browserConfig set for specific sites 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 personal information required

• 🚫 No Complex Configuration - Start with a single command

• 🚫 No Documentation to Learn - Interact directly with natural language

⚡ Ready to Use Immediately

• 📦 Out of the box, no preparation needed

• 🔍 Complete 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

📋 Usage Notes

1. Completely Free - Core features require no fees

2. Follow Guidelines - Please comply with each job platform's terms of use

3. Use Responsibly - It is recommended to control request frequency to avoid excessive access

4. System Requirements - Node.js >= 16.0.0

Open Source License

MIT License

Getting Help

If you encounter any issues while using the service, please get help through the following channels:

• Submit a GitHub Issue