hh-cv-mcp: full hh.ru job-seeker toolkit
hh-cv-mcp
A cookie-session MCP server that gives an agent hh.ru search, applications, chats and resume analytics hidden from job seekers, no official API
High risk
We rate an entry high when the tool writes to external systems, handles money, production databases or secrets, or runs arbitrary commands. The CLI installs it only with your consent.
Why this level
- apply, chat_send and cv_push write to the live account immediately, with no confirmation or dry-run
- Access goes through a session cookie rather than an official API, which may violate hh.ru's rules
- The hhtoken cookie is effectively an account access key and must be kept secret
Install
Manual install
python3 hh_client.py session --cookie 'hhtoken=...; _xsrf=...'Saving a session from a logged-in hh.ru cookie, after simply copying the repository folder.
This is third-party code. Review the repository files before installing.
What it does
After hh.ru closed its public applicant API in December 2025, the server restores the same functionality through the internal JSON the site itself serves to a browser with a logged-in session cookie; the protocol is documented by observation, not officially. Two plain-Python files with no third-party dependencies expose roughly thirty tools: vacancy search and recommendations, vacancy assessment and employer contacts, applying and cover letters, inbox and chats, and resume upkeep and edits. It separately surfaces data hh.ru hides from job seekers: resume_scorecard shows hh's own 7-day funnel of views and invitations, resume_views shows which employers opened the resume, resume_advice is a critique from hh's internal LLM, and thread_read_state shows whether the last message was read. Eleven write tools execute immediately with no confirmation or dry-run: apply submits an application, chat_send sends a message, cv_push overwrites the live resume, and the only safeguard is honest MCP annotations (readOnlyHint / destructiveHint) for the client to act on.
Who it is for. For job seekers willing to let an agent directly operate their hh.ru account, understanding that writes execute immediately with no confirmation.
Good fit when
- The official applicant API is closed but you need full access: search, applications, chats, resume upkeep
- You need resume analytics hh.ru doesn't show directly: the view funnel, who viewed the resume, hh's own critique
- You've added your own confirmation gate in front of an autonomous agent and understand what each write tool does
Not a fit when
- You don't want to rely on unofficial cookie-based access instead of a documented API: there simply is no official option for job seekers right now
- You're pointing this at a fully autonomous agent with no confirmation gate of your own: apply and chat_send will fire without asking
- You need commercial use: the PolyForm Noncommercial license only allows noncommercial use
Example request
Show which employers viewed my resume in the last week, and give me hh's own critique of itLimitations
The source is licensed under PolyForm Noncommercial License 1.0.0, not MIT: commercial use requires a separate license via an issue request. The protocol was reverse-engineered by observing the site rather than from hh's documentation, so it can break when hh changes something; a smoke.py test against a live session exists for that. The hhtoken cookie lasts a few weeks and must be re-extracted from browser DevTools. The server has no built-in write safeguard at all: 11 tools, including apply, chat_send and cv_push, execute immediately, and the author explicitly advises adding an external confirmation gate for autonomous LLMs.
How to disable. Remove the hh block from mcpServers in your client configuration and delete the local repository copy along with the .hh_session.json session file.
MCP
- Transport
- stdio
- Authentication
- not required
| Environment variables | |
|---|---|
| HH_SESSION required, secret | Path to the session file with the hh.ru cookie, created by the session command. |
| HH_CURRENCY | Default currency for salary entries, RUR if unset. |
Security check
- apply, chat_send and cv_push write to the live account immediately, with no confirmation or dry-run
- Access goes through a session cookie rather than an official API, which may violate hh.ru's rules
- The hhtoken cookie is effectively an account access key and must be kept secret
README in short
The bilingual README explains that hh.ru closed its public applicant API on December 15, 2025, and describes a protocol reconstructed by observation over a cookie session. It lists scenarios from authentication to resume upkeep, separately calling out tools that expose analytics hidden from job seekers. It explicitly states that 11 write tools execute with no confirmation and advises adding an external gate for autonomous LLMs. There's a table of typical errors and a test section with sessionless fixtures plus a live smoke test. PolyForm Noncommercial License 1.0.0.
FAQ
Do I need an official hh.ru API token?
No, the official applicant API has been closed since December 2025; the server works through a logged-in browser session cookie.
Could the agent accidentally submit an application?
Yes, unless you add your own confirmation gate: apply and the other 10 write tools execute immediately with no dry-run, which is a deliberate author choice, not an oversight.
Related
A self-hosted knowledge base with block-level references and a built-in MCP server for connecting AI agents to your notes
A CLI for every Google Workspace API with JSON output and agent skills: Drive, Gmail, Calendar, Sheets and more
Local search over Markdown notes, docs and meeting transcripts: keywords, semantic search and reranking, with an MCP server
A task manager for AI-driven development: breaks a PRD into dependent tasks and guides the agent through them via MCP or CLI