ActiveVacancies MCP Server
by rasmuslinkin
README.md
# ActiveVacancies MCP Server
[](https://www.npmjs.com/package/@activevacancies/mcp-server)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
[](https://nodejs.org)
[](https://github.com/rasmuslinkin/activevacancies-mcp/actions)
[](https://github.com/rasmuslinkin/activevacancies-mcp/pkgs/container/activevacancies-mcp)
The official **Model Context Protocol (MCP)** server for [ActiveVacancies](https://activevacancies.com) — connecting AI assistants directly to real-time, verified tech job listings, compensation percentiles, company ATS pipelines, and candidate skill matchmaking.
---
## 🌟 Key Features
- 🔍 **Real-Time Job Search**: Query verified tech jobs by role, remote status (`remote`, `hybrid`, `onsite`), salary minimums, tech stack keywords, and locations.
- 🎯 **AI Resume Matchmaker**: Score candidate resumes and tech skills against active vacancies with weighted ranking ($0$–$100\%$) across skills, title relevance, remote preference, and compensation compatibility.
- 💰 **Salary Intelligence**: Instant salary distribution analysis (25th percentile, median, 75th percentile, and ASCII compensation curve) across titles and geographies.
- ⚡ **Zero-Stale Verification**: Active direct-to-ATS links verified through continuous prober health checks.
- 🤖 **Pre-Packaged Agent Prompts**: Built-in `career-coach` and `salary-negotiator` workflows that guide LLMs through structured job search and offer negotiation strategies.
- 📦 **Multi-Client Ready**: Native 1-click support for Claude Desktop, Cursor IDE, Antigravity IDE, Claude Code CLI, and Docker.
---
## 🚀 Quick Start & Installation
### Option 1: Claude Desktop
Add the server to your `claude_desktop_config.json`:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"activevacancies": {
"command": "npx",
"args": ["-y", "@activevacancies/mcp-server"]
}
}
}
```
### Option 2: Cursor IDE
Add to `.cursor/mcp.json` or **Settings > Features > MCP Servers**:
```json
{
"mcpServers": {
"activevacancies": {
"command": "npx",
"args": ["-y", "@activevacancies/mcp-server"]
}
}
}
```
### Option 3: Claude Code CLI
Add directly to your Claude Code workspace:
```bash
claude mcp add activevacancies -- npx -y @activevacancies/mcp-server
```
### Option 4: Docker Container
Run directly via GitHub Container Registry (GHCR):
```bash
docker run -i --rm ghcr.io/rasmuslinkin/activevacancies-mcp:latest
```
---
## 🛠️ MCP Tools Reference
### 1. `search_jobs`
Search active, verified tech job listings with expressive multi-attribute filters.
| Parameter | Type | Required | Description |
|:---|:---|:---:|:---|
| `query` | `string` | No | Keyword query (e.g., `"staff backend engineer"`, `"rust"`). |
| `remote_status` | `enum` | No | `"remote"`, `"hybrid"`, `"onsite"`, or `"any"`. |
| `location` | `string` | No | Location query (e.g., `"San Francisco"`, `"Europe"`, `"Worldwide"`). |
| `employment_type` | `string` | No | `"full-time"`, `"contract"`, `"part-time"`, `"internship"`. |
| `min_salary` | `number` | No | Minimum annual base salary threshold. |
| `currency` | `string` | No | ISO currency code (defaults to `"USD"`). |
| `company_slug` | `string` | No | Target company slug identifier. |
| `sort_by` | `enum` | No | `"verified_desc"` (default), `"salary_desc"`, `"date_desc"`. |
| `limit` | `number` | No | Results per page (default: `10`, max: `50`). |
| `page` | `number` | No | Pagination page index (1-based). |
---
### 2. `get_job_details`
Retrieve complete role requirements, team details, verified salary ranges, and direct application links.
| Parameter | Type | Required | Description |
|:---|:---|:---:|:---|
| `job_id_or_slug` | `string` | **Yes** | Numeric job ID or URL slug. |
---
### 3. `match_resume_to_jobs`
Match candidate CV skills, target role, and location preferences against live vacancies using deterministic weighted scoring.
| Parameter | Type | Required | Description |
|:---|:---|:---:|:---|
| `candidate_skills` | `string[]` | **Yes** | Array of technical skills (e.g. `["Go", "Kubernetes", "PostgreSQL"]`). |
| `target_title` | `string` | No | Ideal role title (e.g. `"Lead Infrastructure Engineer"`). |
| `remote_status` | `enum` | No | Candidate remote preference (`"remote"`, `"hybrid"`, `"onsite"`). |
| `preferred_location`| `string` | No | Geographic constraint. |
| `min_salary` | `number` | No | Desired annual compensation floor. |
| `currency` | `string` | No | Currency code (defaults to `"USD"`). |
| `limit` | `number` | No | Number of top matches to return (default: `5`, max: `20`). |
---
### 4. `get_salary_benchmarks`
Query market compensation percentiles and ASCII distribution curves for technical titles.
| Parameter | Type | Required | Description |
|:---|:---|:---:|:---|
| `role` | `string` | **Yes** | Role title (e.g. `"Staff Software Engineer"`). |
| `location` | `string` | No | Location filter (e.g. `"United States"`, `"Remote"`). |
| `currency` | `string` | No | ISO currency code (defaults to `"USD"`). |
---
### 5. `list_companies`
List actively hiring tech companies and ATS systems represented on ActiveVacancies.
| Parameter | Type | Required | Description |
|:---|:---|:---:|:---|
| `limit` | `number` | No | Maximum companies to retrieve (default: `25`). |
| `search` | `string` | No | Optional company name filter. |
---
### 6. `report_expired_job`
Submit community feedback on expired or filled listings to trigger immediate background verification.
| Parameter | Type | Required | Description |
|:---|:---|:---:|:---|
| `job_id_or_slug` | `string` | **Yes** | Target job identifier. |
| `reason` | `string` | No | Context regarding closure (e.g., `"404 on ATS link"`). |
---
## 📚 Resources & Prompts
### Resources
- `jobs://feed/latest`: Top 30 most recently verified jobs in markdown table format.
- `jobs://stats/market-summary`: Real-time aggregated hiring metrics, remote percentages, and top hiring engineering departments.
### Workflows & Prompts
- `career-coach`: Initiates an interactive career advisory session to evaluate candidate preferences, run skill matchmaking, and generate customized application pitches.
- `salary-negotiator`: Analyzes compensation offers against market percentiles (`get_salary_benchmarks`) and drafts tailored counter-offer negotiation scripts.
---
## ⚙️ Environment Configuration
| Variable | Default | Description |
|:---|:---|:---|
| `ACTIVEVACANCIES_API_URL` | `https://activevacancies.com/api/v1` | ActiveVacancies gateway API base endpoint. |
| `ACTIVEVACANCIES_API_KEY` | *(None)* | Optional API key for elevated rate limits. |
---
## 💻 Local Development & Testing
```bash
# Clone the repository
git clone https://github.com/rasmuslinkin/activevacancies-mcp.git
cd activevacancies-mcp
# Install dependencies
npm ci
# Typecheck and build
npm run typecheck
npm run build
# Run Vitest test suite
npm test
# Run dogfood health check against local endpoint
ACTIVEVACANCIES_API_URL=http://localhost:3000/api/v1 npm run dogfood
```
---
## 📄 License
Distributed under the [MIT License](LICENSE). Copyright © 2026 ActiveVacancies / Rasmus Linkin.
TDQS
A3.9/5.0
Scored across 6 tools
Disambiguation5/5
Each tool targets a distinct job-search workflow: searching, viewing details, listing companies, reporting expired postings, resume matching, and salary benchmarking. There is no meaningful overlap between tool responsibilities.
Naming Consistency5/5
All tool names follow a consistent snake_case verb_noun pattern (search_jobs, get_job_details, list_companies, report_expired_job, match_resume_to_jobs, get_salary_benchmarks). The naming style is uniform and predictable.
Tool Count5/5
Six tools is a well-scoped set for a job vacancy and market-data server. Each tool provides a meaningful and non-redundant capability without overloading the interface.
Completeness5/5
The tool surface covers the core candidate workflow: discovery, details, company exploration, resume matching, salary insights, and a feedback loop for expired jobs. No obvious critical gaps exist for the stated purpose.