SkillFoxx

hh-relay: public hh.ru search relay

hh-relay

A read-only relay over api.hh.ru: it holds its own app OAuth token and exposes vacancy search and details via MCP and ChatGPT Actions, no user keys

  • 0 ★ on the repository
  • Last commit
MCP server

Extended access

Why this level

  • The author's public server searches hh.ru vacancies via the official API
  • Agent queries go to hh-relay.vercel.app, no job seeker account access
All reasons and checks
Russian stack

syrenny/hh-relayAuthor:Syrenny

Install

Services

In your terminal, with SkillFoxx CLI

npx skillfoxx add mcp/hh-relay

Detects the agents on your machine, shows the access level and pins the version.

Other ways to install

Access and checks

How we review

Extended accessThe tool runs code or makes network calls and only reads external data.

  • The author's public server searches hh.ru vacancies via the official API
  • Agent queries go to hh-relay.vercel.app, no job seeker account access

This is third-party code. Review the repository files before installing.

What it does

hh.ru requires clients to use OAuth 2.0 Client Credentials to reach its official API, so the relay holds an approved hh.ru app's client_id and client_secret server-side and fetches the application token itself, while public relay clients go through no authorization at all. The REST endpoints GET /api/vacancies/search (up to 50 unique vacancies from the last 24 hours, filterable by region and experience) and GET /api/vacancies/{id} return normalized data, with the description field's untrusted HTML from hh.ru explicitly flagged as needing safe handling on the client side. A separate stateless MCP endpoint /mcp exposes two read-only tools: search_vacancies and get_vacancy. Errors from hh.ru (403, 429, a changed response shape) turn into stable codes like upstream_forbidden or upstream_structure_changed, and logs contain only the request path and exception type, no tokens or search text. Two ready-made skills ship with it: searching Python vacancies and drafting a cover letter from a vacancy card through the same MCP.

Who it is for. For ChatGPT Actions and MCP client developers who need public hh.ru vacancy search without registering their own app or handling OAuth.

Good fit when

  • You need hh.ru search and vacancy details without registering your own app and handling OAuth keys
  • You want a stable error format instead of parsing api.hh.ru's codes and response shape directly
  • You want ready-made skills for Python vacancy search and cover letter drafting

Not a fit when

  • You need personal account data: applications, resumes, messages. The relay only handles public vacancy search via an application token
  • You need more than 50 vacancies per search or results older than 24 hours: the relay deliberately limits results
  • You need your own physically isolated server rather than the shared public https://hh-relay.vercel.app

Example request

Find Python FastAPI vacancies in Moscow with 1-3 years of experience from the last day

MCP

Transport
http
Authentication
not required

Environment variables

HH_CLIENT_ID required, secret
Client ID of an approved hh.ru app, needed only to run your own relay instance.
HH_CLIENT_SECRET required, secret
The Client Secret for the same hh.ru app.

Limitations

The repository has no stated license. Running your own instance needs an approved hh.ru app with client_id and client_secret; the README explicitly warns not to pass them to public endpoints or commit them to Git. Search is limited to the last 24 hours and 50 unique vacancies per call. The creation_time field is always empty because the official API doesn't provide a separate confirmed value.

How to disable. Remove the hh-relay block from your MCP client configuration or your Custom GPT Action settings.

FAQ

Does a user need an hh.ru key to search vacancies?

No, public relay clients go through no authorization at all; only the relay itself holds the keys.

Can the relay apply to a vacancy or show my personal data?

No, it only has two read-only tools for search and vacancy details via an application token, with no access to a personal account.

Discussion

No questions or reviews yet.

All hh.ru tools
Russian stack

An MCP server for the employer side of the hh.ru and hh.kz API: your vacancies, applications, resume search, sourcing and webhooks through an OAuth app

MCP serverBroad access1
Russian stack

An MCP server with 52 tools over the official hh.ru API: vacancy search with no token, employer resumes and applications with one, and salary statistics

MCP serverExtended access
Russian stack

A FastMCP server with 43 hh.ru tools: signs in via the official hh.ru Android app's OAuth, no need to register your own app at dev.hh.ru

MCP serverBroad access

hh.ru MCP

hh-mcp

Russian stack

MCP server for the hh.ru API: vacancy and employer search, salary estimates, reference lists, resumes with employer access

MCP serverExtended access10
Russian stack

A browser-based MCP server for job search on hh.ru: resume-matched vacancy recommendations, applications and statuses

MCP serverBroad access3

README in short

The README describes a FastAPI relay for Custom GPT Actions and MCP that fetches its own application token via OAuth 2.0 Client Credentials and serves hh.ru vacancy search. It lists REST endpoints with curl examples, a full table of upstream error codes, an MCP-for-ChatGPT section with a public no-auth address, and Vercel deploy steps with environment variables. Tests use anonymized fixtures and never call hh.ru.

README badge

Report a problem