Content
# mcp-jobs
🚀 **Zero-Configuration** multi-platform job aggregation service! Based on MCP architecture, it supports obtaining job information from mainstream recruitment websites, **out-of-the-box, without any settings**.
[![NPM Version][npm-image]][npm-url]
[![Node.js Version][node-version-image]][node-version-url]
[![License][license-image]][license-url]
## ⚡ 30 Second Quick Start
### 🚀 Step 1: Start the service (zero configuration)
```bash
# One-line command to start immediately
npx -y mcp-jobs
```
### 🤖 Step 2: Configure 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 blank
### 💬 Step 3: Start Using
Say directly to the AI assistant: *"Search for front-end development jobs in Beijing"*
**It's that simple!** 🎉 No registration, no API Key, no configuration file required.
## 🌟 Core Features
- **🔓 Zero Threshold**: No API Key, no registration, no configuration required
- **📦 Out-of-the-box**: One line of command to start the complete service
- **🔍 Intelligent Search**: Supports filtering by job title, city, salary range, etc.
- **🌐 Multi-Platform Aggregation**: Automatically retrieves data from multiple mainstream recruitment websites
- **📊 Standardized Output**: Unified data format for easy processing by large models
- **⚡ Real-Time Updates**: Ensures the timeliness of job information
- **🔧 Optional Enhancements**: Supports API Key to unlock additional features (completely optional)
## 📦 Installation Method
### 🚀 Instant Run (Recommended)
**No installation, no configuration, use immediately:**
```bash
# One-line 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
# Run directly
mcp-jobs
```
### 📁 Project Installation (Optional)
```bash
# Install to project dependencies
npm install mcp-jobs
# Or use yarn
yarn add mcp-jobs
# Or use pnpm
pnpm add mcp-jobs
```
## 🎯 Instructions for Use
### 🚀 Basic Usage (Zero Configuration)
**Start immediately without any settings:**
```bash
# Start the service
npx -y mcp-jobs
# The service will automatically provide the following functions:
# ✅ Job search
# ✅ Job details acquisition
# ✅ Multi-platform data aggregation
# ✅ Standardized data output
```
**It's that simple!**
### 🔧 Advanced Configuration (Completely Optional)
If you need additional enhancements, you can optionally configure the following parameters:
```bash
# Optional: Copy the configuration template
cp .env.example .env
# Optional: Edit the configuration file and 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 (can be 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 Instructions
| 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)
#### Simplest 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):**
```json
{
"mcpServers": {
"mcp-jobs": {
"command": "npx",
"args": ["-y", "mcp-jobs"]
}
}
}
```
**Advanced Configuration (Optional Enhancement):**
```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, which provides complete job search functionality!
### 🤖 Claude Desktop Configuration
**Zero Configuration Settings:**
1. Open Claude Desktop
2. Click 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 required)
**That's it!** No API Key required, ready to use.
### 🚀 Windsurf Configuration
**Basic Configuration (Zero Settings):**
```json
{
"mcpServers": {
"mcp-jobs": {
"command": "npx",
"args": ["-y", "mcp-jobs"]
}
}
}
```
### 🚀 Cline Configuration
**Basic Configuration (Zero Settings):**
```yaml
mcp:
servers:
mcp-jobs:
command: npx
args: ["-y", "mcp-jobs"]
```
## 🔧 Advanced Configuration (Completely Optional)
> ⚠️ **Important Note**: All of the following configurations are **completely optional**! The service provides 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 Again**: No configuration is required to use the full job search functionality!
## 🎯 Start Using Now
After the configuration is complete (just one line of command!), you can describe your job search needs to the AI assistant in natural language:
### 💬 Usage Examples
**Directly search for jobs:**
- "Search for front-end development engineer jobs in Shanghai"
- "Find data analyst positions in Beijing, requiring more than 3 years of experience"
- "Find the highest-paid product manager positions in Hangzhou"
**Get job details:**
- "Get detailed information about this job: [Job Link]"
- "Analyze the requirements and salary of this position"
**Intelligent Analysis:**
- "Compare the salary levels of similar positions in different cities"
- "Summarize the popular skill requirements in the current market"
> 🚀 **Zero-Threshold Experience**: No need to learn complex API calls, you can get professional job search services directly in natural language!
The large model will automatically call the mcp-jobs service to obtain 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 visual browser window (non-headless mode)
CRAWLER_HEADLESS=false npx -y mcp-jobs
# Enable debug logs
CRAWLER_DEBUG=true npx -y mcp-jobs
# Use in combination
CRAWLER_HEADLESS=false CRAWLER_DEBUG=true npx -y mcp-jobs
```
### ⚙️ Custom Browser Configuration
```bash
# Custom viewport size
CRAWLER_VIEWPORT_WIDTH=1920 CRAWLER_VIEWPORT_HEIGHT=1080 npx -y mcp-jobs
# Increase timeout (suitable for slow networks)
CRAWLER_TIMEOUT=60000 npx -y mcp-jobs
# Custom user agent
CRAWLER_USER_AGENT="Custom Bot 1.0" npx -y mcp-jobs
```
### 📝 Configuration Priority
The priority of configuration 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 default values
## 🌟 Why Choose MCP Jobs?
### ✅ **Truly Zero Threshold**
- 🚫 **No Account Registration Required** - No need to fill in any personal information
- 🚫 **No Complex Configuration Required** - One line of command to start
- 🚫 **No Need to Learn Documentation** - Interact directly in natural language
### ⚡ **Ready to Use**
- 📦 Out-of-the-box, no preparation required
- 🔍 Complete job search function
- 🌐 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 functions are free of charge
2. **Comply with Specifications** - Please comply with the usage agreements of each recruitment platform
3. **Reasonable Use** - It is recommended to control the request frequency and avoid excessive access
4. **System Requirements** - Node.js >= 16.0.0
## Open Source License
[MIT License](LICENSE)
## Get Help
If you encounter any problems during use, please get help through the following methods:
- Submit [GitHub Issue](https://github.com/mergedao/mcp-jobs/issues)
[npm-image]: https://img.shields.io/npm/v/mcp-jobs.svg
[npm-url]: https://npmjs.org/package/mcp-jobs
[node-version-image]: https://img.shields.io/node/v/mcp-jobs.svg
[node-version-url]: https://nodejs.org/download/
[license-image]: https://img.shields.io/npm/l/mcp-jobs.svg
[license-url]: LICENSE
