hh-mcp-ru

hh-mcp-ru

API hh.ru para assistentes de IA: vagas, respostas e convites, currículos, diretórios, estatísticas salariais. Catálogo da especificação oficial, cada método com classe de acesso.

O catálogo foi montado a partir da fonte original (especificação oficial api.hh.ru/openapi/specification/public) e está no repositório como hh_mcp/endpoints.yaml: 133 métodos, sendo 92 de leitura, 32 de escrita e 9 irreversíveis. O servidor executa exatamente esse arquivo, portanto a tabela abaixo não pode divergir do código.

Instalação

uvx hh-mcp-ru

Claude Desktop, claude_desktop_config.json:

{
  "mcpServers": {
    "hh-mcp": {
      "command": "uvx",
      "args": ["hh-mcp-ru"],
      "env": { "HH_TOKEN": "...", "HH_APP_NAME": "..." }
    }
  }
}

Chaves

dev.hh.ru → Meus aplicativos → criar aplicativo → access token. HH_APP_NAME é preenchido obrigatoriamente: o hh rejeita requisições sem um User-Agent claro, e essa é a primeira causa de erros 400 inexplicáveis.

variável	segredo	o que é
HH_TOKEN	sim	Token do aplicativo hh.ru (dev.hh.ru → Meus aplicativos).
HH_APP_NAME	não	Nome do aplicativo e e-mail de contato para o cabeçalho HH-User-Agent: sem ele, o hh rejeita requisições.

As chaves não precisam ficar no ambiente: o servidor suporta cofres e as armazena em ~/.ru-mcp/cabinets.json com permissões 600, fora do repositório.

Mapa de métodos

seção	métodos	leitura	escrita	irreversível
Empregador e gerentes	30	23	5	2
Vagas	21	12	7	2
Diretórios gerais	14	6	7	1
Sugestões	11	11	0	0
Respostas e convites	10	5	5	0
Buscas salvas	6	2	3	1
Estatísticas salariais	5	5	0	0
Webhooks	4	1	2	1
Comentários sobre candidatos	4	1	2	1
Currículos	3	3	0	0
Chamadas	3	3	0	0
Regiões	3	3	0	0
Tokens	2	0	1	1
Instituições de ensino	2	2	0	0
Locais	2	2	0	0
Metrô	2	2	0	0
Usuário atual	1	1	0	0
Contas de gerentes	1	1	0	0
Setores	1	1	0	0
Dicionários	1	1	0	0
Papéis profissionais	1	1	0	0
Idiomas	1	1	0	0
Habilidades	1	1	0	0
Clickme	1	1	0	0
Distritos	1	1	0	0
Modelos de mensagens	1	1	0	0
Condições de publicação de vagas	1	1	0	0
total	133	92	32	9

Como fica no chat

Você: busca de vagas

hh_search_methods("поиск вакансий")
  hh_get_vacancies                     GET  /vacancies                                 чтение
  hh_get_vacancies_related_to_vacancy  GET  /vacancies/{vacancy_id}/related_vacancies  чтение
  hh_get_vacancies_similar_to_vacancy  GET  /vacancies/{vacancy_id}/similar_vacancies  чтение

hh_describe_method("hh_get_vacancies")
  Поиск по вакансиям
  GET api.hh.ru/vacancies
  параметры: page, per_page, text, search_field, experience, employment, schedule, area и ещё 36
  класс доступа: чтение

hh_call_method("hh_get_vacancies", {"page": "...", "per_page": "..."})

Três ferramentas em vez de 133 funções: o agente encontra o método por palavras, lê o cartão dele e o chama. Escrita e ações irreversíveis pedem confirmação.

O que costumam pedir:

• Exportar suas vagas e respostas por período e consolidar em uma tabela.
• Ver estatísticas salariais por papel antes de publicar uma vaga.
• Encontrar vagas de concorrentes por região e papel profissional.
• Responder candidatos com modelo, mostrando a lista à pessoa antes do envio.

Segurança

O servidor roda na máquina do usuário, as chaves não saem para fora. Os métodos têm três classes de acesso: leitura é imediata, escrita e ações irreversíveis exigem confirmação. O cabeçalho de autorização não sai dos domínios do serviço mesmo ao chamar um caminho arbitrário.

Verificar instalação

uvx hh-mcp-ru doctor

Mostra quantos métodos foram carregados, se as chaves foram encontradas e de onde. Segredos não são exibidos. Com --live faz uma chamada real barata de leitura.

Relacionados

O núcleo foi extraído para schema-mcp-core. Servidores vizinhos: vk-mcp-ru, diadoc-mcp-ru, sbis-mcp-ru, chestny-znak-mcp-ru. Os marketplaces ficam separados: marketplaces-mcp-ru.

MIT. Autor Ilya Utov.

Todos os projetos em uma lista, organizados por finalidade: ilyautov.github.io.