Content
# mcp-jobs
🚀 **Zero Configuration** Multi-platform Job Aggregation Service! Based on MCP architecture, supports fetching job information from mainstream recruitment websites, **out of the box, no configuration required**.
[![NPM Version][npm-image]][npm-url]
[![Node.js Version][node-version-image]][node-version-url]
[![License][license-image]][license-url]
## ⚡ Quick Start in 30 Seconds
### 🚀 Step 1: Start Service (Zero Configuration)
```bash
# One-line command to start immediately
npx -y mcp-jobs
```
### 🤖 Step 2: Configure AI Client
Add to your AI client (e.g., Cursor, Claude Desktop):
- **Service Name**: `mcp-jobs`
- **Command**: `npx -y mcp-jobs`
- **Environment Variables**: Leave empty
### 💬 Step 3: Start Using
Directly tell the AI assistant: *"Search for front-end development jobs in Beijing"*
**That's it!** 🎉 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 command to start the complete service
- **🔍 Intelligent Search**: Supports filtering by job name, city, salary range, etc.
- **🌐 Multi-platform Aggregation**: Automatically fetches data from multiple mainstream recruitment websites
- **📊 Standardized Output**: Unified data format for easy processing by large models
- **⚡ Real-time Updates**: Ensures timeliness of job information
- **🔧 Optional Enhancements**: Supports API Key to unlock additional features (completely optional)
## 📦 Installation Methods
### 🚀 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 frequently:
```bash
# Global installation
npm install -g mcp-jobs
# Direct run
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
```
## 🎯 Usage Instructions
### 🚀 Basic Usage (Zero Configuration)
**No configuration required, start immediately:**
```bash
# Start service
npx -y mcp-jobs
# Service will automatically provide the following functions:
# ✅ Job search
# ✅ Job details retrieval
# ✅ Multi-platform data aggregation
# ✅ Standardized data output
```
**That's it!**
### 🔧 Advanced Configuration (Completely Optional)
If you need additional enhancements, you can optionally configure the following parameters:
```bash
# Optional: Copy configuration template
cp .env.example .env
# Optional: Edit configuration file, uncomment needed features
# 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 Description
| Configuration | 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 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
**Basic Configuration (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**: Recommended to use basic configuration, which provides complete job search functionality!
### 🤖 Claude Desktop Configuration
**Zero-configuration settings:**
1. Open Claude Desktop
2. Click on the Settings icon at the bottom left
3. Select "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 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 configurations are **completely optional**! The service provides complete 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**: No configuration required to use complete job search functionality!
## 🎯 Start Using Immediately
After configuration (just one line of command!), you can describe job search requirements to the AI assistant in natural language:
### 💬 Usage Examples
**Direct Job Search:**
- "Search for front-end development jobs in Shanghai"
- "Find data analyst positions in Beijing with over 3 years of experience"
- "Find product manager positions with the highest salary in Hangzhou"
**Get Job Details:**
- "Get detailed information about this job: [job link]"
- "Analyze the requirements and salary of this position"
**Intelligent Analysis:**
- "Compare salary levels of similar positions in different cities"
- "Summarize popular skills required in the current market"
> 🚀 **Zero-threshold Experience**: No need to learn complex API calls, directly use natural language to get professional job search services!
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, 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 together
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 (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
Configuration priority from high to low:
1. **Site-specific configuration** - `browserConfig` set for specific websites in `crawlerConfig.ts`
2. **Environment variables** - set through `CRAWLER_*` environment variables
3. **Default configuration** - system default values
## 🌟 Why Choose MCP Jobs?
### ✅ **Truly Zero Threshold**
- 🚫 **No registration required** - no personal information needed
- 🚫 **No complex configuration** - one-line command to start
- 🚫 **No documentation required** - directly interact with natural language
### ⚡ **Ready to Use**
- 📦 Out of the box, no preparation required
- 🔍 Complete job search functionality
- 🌐 Multi-platform data aggregation
- 📊 Standardized data output
### 🛡️ **Reliable and Stable**
- 🔄 Automatic retry mechanism
- ⚠️ Elegant error handling
- 📈 Real-time data updates
- 🔧 Optional advanced features
## 📋 Terms of Use
1. **Completely free** - core features without any cost
2. **Follow regulations** - please comply with the usage agreements of each recruitment platform
3. **Reasonable use** - suggest controlling request frequency to avoid excessive access
4. **System requirements** - Node.js >= 16.0.0
## Open-source License
[MIT License](LICENSE)
## Get Help
If you encounter any issues during use, please get help through:
- 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
