Skip to main content
Glama
ComPanS

hh-vacancy-mcp

by ComPanS

HH Vacancy MCP

MCP server for Claude Code that searches HH.ru using an authenticated browser session and returns vacancies matching a resume.

Features

  • TypeScript MCP server over stdio.

  • Playwright browser control.

  • Chrome/Edge CDP connection to reuse an existing logged-in session.

  • Persistent profile mode for Chrome, Edge, or Firefox.

  • Local deterministic 0–100 resume matching score.

  • Default minimum score: 70; change it with set_min_score or the bundled Claude Code skill.

  • No HH.ru credentials are collected or stored.

Related MCP server: HH MCP Server

Install

npm install
npx playwright install chromium firefox
npm run build

Claude Code MCP configuration

Add the built server to Claude Code's MCP configuration:

{
  "mcpServers": {
    "hh-vacancy-mcp": {
      "command": "node",
      "args": ["C:/Users/nazmi/Documents/GitHub/hh-vacancy-mcp/dist/src/index.js"]
    }
  }
}

Reuse a logged-in Chrome or Edge session

Close the normal browser instance, then start a separate instance with remote debugging and a dedicated profile. Example on Windows:

"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" --remote-debugging-port=9222 --user-data-dir="C:\\Users\\<you>\\hh-mcp-profile"

For Edge, use msedge.exe and set browser to edge with set_browser. Open https://hh.ru, log in manually, then use set_browser with mode cdp and search. Cookies remain in the browser profile and are never returned by this server.

Persistent profile mode

Use set_browser with mode: "persistent" and a profile directory. Open HH.ru and authenticate manually once. Firefox should use persistent mode because it does not provide the CDP connection used here.

Typical workflow

  1. set_browser if the default Chrome/CDP settings do not fit.

  2. set_resume with the resume text.

  3. set_min_score with a value from 0 to 100, or keep 70.

  4. search_hh_vacancies with a query and optional area/page limit.

Search is read-only and limited to five result pages per call. HH.ru markup can change; if no cards are found, check the browser session and report the issue rather than guessing.

Development

npm run typecheck
npm test
npm run build

Available Tools

5 tools
get_settingsB

Show current browser and resume matching settings.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. 'Show' suggests a read-only operation, but the description never explicitly states that it does not modify settings, whether it requires any permissions, or what happens if settings are unset. This is a meaningful gap for a tool with no annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler or redundant information. It is appropriately sized for a zero-parameter getter, though it could have used the space to add behavioral context without becoming wordy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With zero parameters and no output schema, the description must stand alone to convey what calling the tool yields. It identifies the returned content as current browser and resume matching settings, but it does not describe the response shape or explicitly confirm read-only behavior. This is minimally adequate for a simple getter but leaves room for improvement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so there is no parameter documentation burden. The baseline of 4 applies because there is nothing for the description to compensate for or clarify regarding parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Show') and identifies a clear resource ('current browser and resume matching settings'), making it evident this is a read/inspection tool. It is distinguishable from sibling setters like set_browser and set_resume, though it does not name them. The phrase 'matching settings' is slightly ambiguous, preventing a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The verb 'show' implies this tool is for reading current state, likely before using sibling setter tools. However, the description does not explicitly state when to use it versus alternatives, nor does it provide any exclusions or conditions. Usage guidance is present only by implication.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_hh_vacanciesA

Search HH.ru in the selected authenticated browser and return only vacancies meeting the configured score threshold.

ParametersJSON Schema
NameRequiredDescriptionDefault
areaNo
queryYes
pageLimitNo

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of disclosing behavior. It does disclose that the tool searches via an authenticated browser and filters results by a configured score threshold. However, it does not mention browser side effects, rate limits, authentication failure behavior, or whether the operation modifies any state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no filler. It front-loads the core action and packs the two most important qualifiers—authenticated browser and score threshold—into a compact, readable form.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description establishes the core purpose but is incomplete for safe and correct invocation. There are no annotations, no output schema, and no parameter semantics beyond types/constraints, so the agent cannot confidently know how to use `area` or `pageLimit`, what the result structure is, or what prerequisites must be met.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it does not explain any of the three parameters. The terms 'area' and 'pageLimit' are left entirely to the agent to infer, and 'query' is only implicitly connected to the search action.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Search HH.ru'), the execution context ('selected authenticated browser'), and the key filtering behavior ('only vacancies meeting the configured score threshold'). It is readily distinguishable from siblings like get_settings and set_min_score, which are configuration-oriented.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool: when a search of HH.ru with score-based filtering is needed. It references the 'selected authenticated browser' and 'configured score threshold,' hinting that set_browser and set_min_score are prerequisites, though it does not explicitly name alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_browserC

Choose browser and session connection mode. CDP reuses an already logged-in Chrome or Edge.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNo
cdpUrlNo
browserNo
profileDirNo

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are absent, so the description must carry the full behavioral disclosure. It mentions one behavior: CDP reuses an existing Chrome or Edge session, which is useful. However, it does not disclose any side effects of setting the browser, whether it modifies persistent state, or how it interacts with other tools. This is minimal coverage for a configuration tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise, consisting of two short sentences with no superfluous content. It front-loads the primary purpose and adds one specific behavior. However, it is so brief that it omits crucial details, making it efficient but not adequately informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 4 optional parameters and no output schema, the description is incomplete. It does not explain how the parameters interact, when each mode is appropriate, or what values are expected. The lack of behavioral context beyond the CDP reuse note leaves agents guessing about the full impact of calling this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description does not explain any of the four parameters. It loosely refers to 'browser' and 'session connection mode', but does not map these to the schema properties, nor does it clarify the meaning of 'cdpUrl', 'profileDir', or the enum values for 'mode'. With 0% schema description coverage, the description fails to compensate, leaving agents without guidance on how to fill optional fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to choose a browser and session connection mode. It also adds a specific detail about CDP reusing an already logged-in Chrome or Edge, which helps distinguish it from sibling tools like get_settings or search_hh_vacancies. However, it does not enumerate the exact modes or browser options, leaving that to the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this tool versus alternatives. The only hint is that CDP reuses a logged-in browser, which indirectly suggests a use case, but it does not explain when to choose 'cdp' vs 'persistent' or when this tool should be called in a workflow. Sibling tools are unrelated, so the absence of routing guidance is notable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_min_scoreA

Set the minimum vacancy-to-resume match score from 0 to 100. Default is 70.

ParametersJSON Schema
NameRequiredDescriptionDefault
minScoreYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It states the mutation (set) and the setting's range/default, but does not disclose side effects, persistence, scope (global vs per-user), or whether it affects existing searches. It is not misleading, but lacks behavioral detail beyond the immediate action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence conveys the operation, range, and default with zero excess. The action verb is front-loaded, making it immediately scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter setter with no output schema, the description is largely complete. It covers the key semantics (range, default). It could mention persistence or effect on subsequent searches, but that is a minor omission given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It explains the meaning ('vacancy-to-resume match score') and the range (0-100), which goes beyond the schema's simple number with min/max. It does not name the parameter 'minScore' explicitly, but with a single parameter, that is implied.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb 'Set', a specific resource 'minimum vacancy-to-resume match score', and the value range (0-100). It clearly distinguishes from siblings like get_settings (retrieval) and set_browser/set_resume (other settings).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The usage is implied: this tool sets a threshold before searching for vacancies. It does not explicitly state when to use it vs alternatives, nor does it mention exclusions or prerequisites. The default of 70 gives a hint but no direct guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_resumeA

Store resume text locally for matching. Do not include passwords or unrelated secrets.

ParametersJSON Schema
NameRequiredDescriptionDefault
resumeYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations, so the description carries the behavioral disclosure burden. It does disclose that data is stored locally and warns against including passwords or unrelated secrets. However, it does not describe overwrite behavior, persistence, effects on future matching, or failure modes. Some useful context is present, but significant behavioral traits remain undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with no filler. The core purpose is front-loaded, and the security warning is a valuable addition that earns its place. Nothing extraneous is included.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema and no nested objects, the description provides adequate context: purpose, storage location, and a security caution. It does not explicitly state overwrite semantics or return behavior, but given the low complexity and the self-explanatory 'set' semantics, the description is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description should compensate. The phrase 'resume text' clarifies the intended content of the 'resume' parameter, and the warning about secrets adds a semantic constraint. However, the description does not explain expected format, encoding, or how the stored text is used, leaving the parameter semantics only partially elaborated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action and resource: 'Store resume text locally for matching.' This clearly differentiates the tool from siblings like set_browser, set_min_score, and search_hh_vacancies. An agent can infer immediately what operation this tool performs and on what input.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance is given for when to use this tool versus its alternatives. The phrase 'for matching' gives some contextual hint, but there are no exclusions, prerequisites, or comparisons with sibling tools. An agent must rely on the name and schema alone for usage decisions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.1.0
    • First observedget_settings
    • First observedsearch_hh_vacancies
    • First observedset_browser
    • First observedset_min_score
    • First observedset_resume

TDQS

A3.7/5.0

Scored across 5 tools

Disambiguation5/5

Each tool targets a distinct concern: reading settings, updating the score threshold, choosing the browser, storing the resume, and running the search. There is no meaningful overlap between any of the five tools.

Naming Consistency5/5

The naming follows a clear and consistent verb-based pattern: get_settings, set_min_score, set_browser, set_resume, and search_hh_vacancies. The set_ prefix is used uniformly for configuration changes, and the search tool is action-oriented.

Tool Count5/5

Five tools is well-scoped for this focused MCP server. Each tool represents one essential capability for configuring and running HH.ru vacancy searches against a resume.

Completeness5/5

The tool surface covers the full workflow: configure the match threshold, select an authenticated browser, set the resume text, view current settings, and execute the search. No obvious dead ends or missing lifecycle steps are present for the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to search job vacancies, manage resumes, and apply to jobs on HeadHunter (hh.ru), Russia's largest job search platform. Includes OAuth 2.0 integration for secure job applications and an automated vacancy hunter agent with intelligent matching.
    30
    MIT
  • F
    license
    A
    quality
    D
    maintenance
    Enables to interact with hh.ru (a Russian job platform) through browser automation, allowing users to search for jobs, manage resumes, apply to vacancies with cover letters, and track application statuses via natural language.
    9
    3
    -
  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables searching for jobs in Russia and remote positions from AI assistants using multiple job platforms (hh.ru, Trudvsem, SuperJob, and remote job aggregators).
    1
    -
  • F
    license
    Not graded
    quality
    B
    maintenance
    Enables multi-source tech job search and application with CV-based skill extraction, deduplication, and scoring across HireMeTech, Comeet, and AllJobs, supporting autonomous or supervised workflows.
    1
    -