Content
# mcp-jobs
🚀 **Zero Configuration** multi-platform job aggregation service! Based on the MCP architecture, it supports fetching job information from mainstream job websites, **out of the box, no setup 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 Command to Start Immediately
```
npx -y mcp-jobs
```
### 🤖 Step 2: Configure the AI Client
Add the following in your AI client (such as Cursor, Claude Desktop):
- **Service Name**: `mcp-jobs`
- **Command**: `npx -y mcp-jobs`
- **Environment Variables**: Leave blank
### 💬 Step 3: Get Started
Simply tell the AI assistant: *"Search for front-end development jobs in Beijing"*
**It's that easy!** 🎉 No registration, no API Key, no configuration files needed.
## 🌟 Core Features
- **🔓 Zero Threshold**: No API Key required, no registration needed, no configuration necessary
- **📦 Out of the Box**: Start the complete service with a single command
- **🔍 Intelligent Search**: Supports filtering by job title, city, salary range, and other criteria
- **🌐 Multi-Platform Aggregation**: Automatically gathers data from multiple mainstream job sites
- **📊 Standardized Output**: Unified data format for easier 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 Methods
### 🚀 Instant Run (Recommended)
**No installation, no configuration, use it 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
# Direct Run
mcp-jobs
```
### 📁 Installation within the Project (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)
**Start immediately without any setup:**
```bash
# Start the Service
npx -y mcp-jobs
# The service will automatically provide the following features:
# ✅ Job Search
# ✅ Job Details Retrieval
# ✅ Multi-Platform Data Aggregation
# ✅ Standardized Data Output
```
**It's that simple!**
```
### 🔧 Advanced Configuration (Optional)
If you need additional enhancements, you can optionally configure the following parameters:
```bash
# Optional: Copy 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 during debugging)
# CRAWLER_TIMEOUT=30000 # Optional: Page timeout duration (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 duration (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 configurations.
## 🤖 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**: It is recommended to use the basic configuration, which provides complete 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 Configuration):**
```json
{
"mcpServers": {
"mcp-jobs": {
"command": "npx",
"args": ["-y", "mcp-jobs"]
}
}
}
```
### 🚀 Cline Configuration
**Basic Configuration (Zero Configuration):**
```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 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: Customize MCP Server Address
```
> 💡 **Reminder**: No configuration is needed to use the full job search functionality!
```
## 🎯 Get Started Immediately
Once the configuration is complete (just one command!), you can describe your job search requirements to the AI assistant in natural language:
### 💬 Usage Examples
**Directly Search for Positions:**
- "Search for front-end developer positions in Shanghai"
- "Find data analyst positions in Beijing, requiring over 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 role"
**Intelligent Analysis:**
- "Compare salary levels for similar positions in different cities"
- "Summarize the current market's popular skill requirements"
> 🚀 **Zero Threshold Experience**: No need to learn complex API calls, simply use natural language to access professional job search services!
The large model will automatically call the mcp-jobs service to obtain relevant information and present the results to you.
## 🔧 Debugging and Development
### 🐛 Debug Mode
If you need to debug the 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 Logging
CRAWLER_DEBUG=true npx -y mcp-jobs
# Combined Usage
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
The priority of configurations from highest to lowest:
1. **Site-specific configuration** - `browserConfig` set for specific sites in `crawlerConfig.ts`
2. **Environment variables** - Set through `CRAWLER_*` environment variables
3. **Default configuration** - System default values
## 🌟 Why Choose MCP Jobs?
### ✅ **True Zero Threshold**
- 🚫 **No account registration required** - No need to fill in any personal information
- 🚫 **No complex configuration needed** - Start with a single command
- 🚫 **No documentation learning necessary** - Interact directly using natural language
### ⚡ **Ready to Use**
- 📦 Out of the box, no setup required
- 🔍 Complete job search functionality
- 🌐 Multi-platform data aggregation
- 📊 Standardized data output
### 🛡️ **Reliability and Stability**
- 🔄 Automatic retry mechanism
- ⚠️ Graceful error handling
- 📈 Real-time data updates
- 🔧 Optional advanced features
## 📋 Usage Notes
1. **Completely Free** - Core features are available at no cost
2. **Compliance** - Please adhere to the usage agreements of each recruitment platform
3. **Reasonable Use** - It is recommended to control the 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 seek help through the following ways:
- Submit a [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
