# Hh Mcp Server

> hh.ru MCP server: vacancy search and auto-apply via Playwright, TF-IDF scoring, 19 tools, 41 tests

- **Type:** MCP server
- **Install:** `agentstack add mcp-vadtop-hh-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Vadtop](https://agentstack.voostack.com/s/vadtop)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Vadtop](https://github.com/Vadtop)
- **Source:** https://github.com/Vadtop/hh-mcp-server

## Install

```sh
agentstack add mcp-vadtop-hh-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# HH.ru MCP Server v2.0.0 — AI-powered job hunting after API shutdown

## Why

On December 15, 2025, hh.ru shut down its public API for job seekers. No more `/vacancies` endpoint, no programmatic search, no auto-apply. This server restores full automation by emulating a real browser session via Playwright — search, scoring, cover letters, applications — all through MCP tools callable from any AI assistant.

## What's new in v2

- **Stealth Playwright** — Chrome 133 UA, randomized viewport, anti-bot delays, cookie-based auth persistence
- **GLM-4.6 default model** — via OpenRouter, replaces Gemini; async OpenAI client with 30s timeout
- **FastMCP 3.2.x** — migrated from FastMCP 0.x; stdio + streamable-http transport
- **Deduplication DB** — SQLite-backed `applied.db` prevents duplicate applications
- **Daily application limit** — configurable `MAX_APPLIES_PER_DAY` (default 20)
- **Deadlock-free init** — double-check locking with `asyncio.wait_for` timeout; no more hung browser-tools
- **Error recovery** — failed `browser.start()` resets state; next call retries clean
- **`hh_health_check`** — diagnostic tool for browser, session, lock status
- **Safe page context manager** — pages auto-close after use; no orphan tab leaks
- **60 unit tests** — concurrency, scoring, parsing, apply logic, deduplication

## Quick Start

```bash
git clone https://github.com/YOURNAME/hh-mcp-server.git
cd hh-mcp-server
pip install -r requirements.txt
playwright install chromium
playwright install-deps          # Linux only
cp .env.example .env             # fill in your keys
python auth_once.py              # login to hh.ru (one time)
python run_mcp.py                # starts MCP server on stdio
```

### First-time Login

```bash
python auth_once.py
```

Opens a visible Chromium window — enter your phone and SMS code on hh.ru. Session (cookies + localStorage) persists in `.browser_session/` and is reused automatically. Re-login only when session expires (~30 days).

## MCP Tools (20)

### Search & Browsing

| Tool | Description |
|---|---|
| `hh_search` | Search vacancies by text, salary, region, remote |
| `hh_get_vacancy` | Full vacancy details by ID |
| `hh_get_employer` | Company information |
| `hh_get_similar` | Find similar vacancies |
| `hh_bulk_search` | Search multiple queries at once (remote, all Russia) |
| `hh_health_check` | Diagnostic: browser, session, lock status |

### Applications

| Tool | Description |
|---|---|
| `hh_apply_vacancy` | Apply with AI-generated cover letter |
| `hh_get_applications` | Application history and statuses |
| `hh_generate_letter` | Generate letter without sending |

### Resume

| Tool | Description |
|---|---|
| `hh_get_my_resumes` | List all resumes |
| `hh_get_resume` | Resume details by ID |
| `hh_update_resume` | Update title, salary, about section |

### AI Analytics

| Tool | Description |
|---|---|
| `hh_score_vacancy` | AI relevance scoring 0–100 (TF-IDF + skills + salary) |
| `hh_market_analytics` | Salaries, top skills, top companies for any query |
| `hh_career_advisor` | Career report: gaps, roadmap, forecast |
| `hh_skills_gap` | Skills you have vs. what the market wants |
| `hh_salary_forecast` | Salary forecast after learning new skills |
| `hh_resume_optimizer` | Concrete resume improvement tips |

### Monitoring

| Tool | Description |
|---|---|
| `hh_start_monitor` | Start background response monitoring |
| `hh_stop_monitor` | Stop monitoring |
| `hh_check_monitor` | One-time application status check |

## Connect to Clients

### opencode

Add to your project's `opencode.json`:

```json
{
  "mcpServers": {
    "hh-mcp": {
      "command": "python",
      "args": ["run_mcp.py"],
      "cwd": "/path/to/hh-mcp-server"
    }
  }
}
```

### VS Code (Cline / Continue)

Add to `.vscode/mcp.json` or your MCP settings:

```json
{
  "servers": {
    "hh-mcp": {
      "command": "python",
      "args": ["run_mcp.py"],
      "cwd": "/path/to/hh-mcp-server"
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hh-mcp": {
      "command": "python",
      "args": ["run_mcp.py"],
      "cwd": "/path/to/hh-mcp-server"
    }
  }
}
```

## Architecture

```
┌─────────────────────────────────┐
│          MCP Client             │  (opencode / Claude / VS Code)
│  calls tools via stdio/HTTP     │
└──────────────┬──────────────────┘
               │
┌──────────────▼──────────────────┐
│       FastMCP 3.2 Server        │  20 tools, lazy init, semaphore(5)
└──────┬─────────┬───────────────┘
       │         │
┌──────▼──┐ ┌───▼──────────────┐
│ Services │ │   AI Layer       │
│ vacancy  │ │  scorer (TF-IDF) │
│ apply    │ │  letter_gen      │  OpenRouter → GLM-4.6
│ resume   │ │  career_advisor  │
│ monitor  │ │  market_analyzer │
└──────┬───┘ └──────────────────┘
       │
┌──────▼──────────────────────────┐
│       Browser Layer             │
│  Playwright + Chromium          │  Chrome 133 UA, stealth
│  safe_page ctx manager          │  random viewport, anti-bot
│  auth (cookie persistence)      │  .browser_session/storage.json
└─────────────────────────────────┘
```

## Disclaimer

This project automates interactions with hh.ru via browser emulation. Usage may violate hh.ru's Terms of Service. The author assumes no responsibility for:
- Account restrictions or bans imposed by hh.ru
- Rate limiting or CAPTCHA challenges
- Any consequences of automated job applications

Use responsibly. Set reasonable `MAX_APPLIES_PER_DAY` and `SCORING_THRESHOLD` values. Review cover letters before sending. This tool is intended for personal use only.

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Vadtop](https://github.com/Vadtop)
- **Source:** [Vadtop/hh-mcp-server](https://github.com/Vadtop/hh-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-vadtop-hh-mcp-server
- Seller: https://agentstack.voostack.com/s/vadtop
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.