Content
# mcp-jobs
🚀 **Zero Configuration** Multi-Platform Job Aggregation Service! Based on MCP architecture, supports fetching job information from mainstream recruitment websites, **ready to use 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 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 (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 frontend development jobs in Beijing"*
**That's it!** 🎉 No registration, no API Key, no configuration files needed.
## 🌟 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 the timeliness of job information
- **🔧 Optional Enhancements**: Supports API Key unlocking 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 it 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 the service
npx -y mcp-jobs
# The 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 enhancement 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 Description
| 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 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):**
```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 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 bottom left corner
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 needed)
**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 below 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!
## 🎯 Get Started
After configuration (just one line of command!), you can describe job search needs to the AI assistant in natural language:
### 💬 Usage Examples
**Direct Job Search:**
- "Search for frontend development jobs in Shanghai"
- "Find data analyst positions in Beijing with 3+ years of experience"
- "Find product manager jobs with the highest salary in Hangzhou"
**Job Details Retrieval:**
- "Get detailed information about this job: [job link]"
- "Analyze the requirements and salary for this position"
**Intelligent Analysis:**
- "Compare salary levels for similar jobs in different cities"
- "Summarize the most in-demand skills in the current market"
> 🚀 **Zero Threshold Experience**: No need to learn complex API calls, directly use natural language for professional job search services!
The large model will automatically call the mcp-jobs service to retrieve relevant information and display the results.
## 🔧 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 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 (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 via `CRAWLER_*` environment variables
3. **Default configuration** - system default values
## 🌟 Why Choose MCP Jobs?
### ✅ **True Zero Threshold**
- 🚫 **No account registration required** - no personal information needed
- 🚫 **No complex configuration** - one-line command to start
- 🚫 **No documentation required** - direct natural language interaction
### ⚡ **Ready to Use**
- 📦 Out of the box, no preparation work needed
- 🔍 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 no charge
2. **Follow guidelines** - comply with each recruitment platform's usage protocol
3. **Use reasonably** - 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
