Are you the author? Sign in to claim
huntflow-mcp
MCP server for HuntFlow ATS API v2 — vacancies, candidates, resumes, funnel stages, rejection reasons, comments, accounts. 16 tools, 3 prompts.
Works with HuntFlow v2 (api.huntflow.ru for Russia or api.huntflow.ai for international accounts). Transports: stdio and streamable HTTP. All data is read-only, except for adding comments.
🧑💼 Not a programmer? There is a step-by-step guide in plain language: INSTALL.md
In claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/):
{
"mcpServers": {
"huntflow": {
"command": "npx",
"args": ["-y", "@gaivoronsky/huntflow-mcp"],
"env": {
"HUNTFLOW_TOKEN": "your-token",
"HUNTFLOW_BASE_URL": "https://api.huntflow.ai/v2"
}
}
}
}
After editing the config, fully restart Claude Desktop (⌘Q and reopen).
git clone https://github.com/Gaivoronsky/huntflow-mcp.git
cd huntflow-mcp
npm install
npm run build # → dist/
Run from the built code with node dist/index.js. To connect to Claude Desktop from source, set "command" in the config to the absolute path to node (the GUI does not inherit the shell PATH; e.g. ~/.nvm/versions/node/<version>/bin/node) and "args" to ["/path/to/huntflow-mcp/dist/index.js"].
HUNTFLOW_TOKEN=your-token node dist/index.js --http
# POST /mcp, GET /health on port 3000 (override with PORT=...)
https://huntflow.ai/token_request/<hash>. Do not open it "just to check" — that deactivates it. Open it in a browser under your account and click Receive.access_token (a long string) into HUNTFLOW_TOKEN.The
access_tokenlives for 7 days, therefresh_tokenfor 14. The server does not refresh the token automatically — once it expires, obtain a new token again.
| Variable | Required | Description |
|---|---|---|
HUNTFLOW_TOKEN | yes | API token (Settings → API) |
HUNTFLOW_BASE_URL | no | Defaults to https://api.huntflow.ru/v2. For an international account — https://api.huntflow.ai/v2 |
HUNTFLOW_USER_AGENT | no | The User-Agent header (HuntFlow requires it). Default huntflow-mcp/<version> (+repo); a contact email is recommended |
PORT | no | HTTP server port (defaults to 3000) |
| Tool | Description |
|---|---|
list_accounts | List of available accounts |
list_vacancies | List of vacancies (open/all), pagination page/count |
get_vacancy | Full information about a vacancy |
list_applicants | Candidates filtered by vacancy/status, pagination (count≤30) |
search_applicants | Full-text search of candidates (q, field), pagination (count≤100) |
get_applicant | Full candidate card (external[], links[]) |
get_applicant_resume | Resume (CV) with body by external_id (from get_applicant) |
list_stages | Recruiting funnel stages (statuses): code → name |
list_rejection_reasons | Reference list of rejection reasons: code → name |
list_account_sources | Resume sources (e.g. RG, HeadHunter): id → name/type. Use the id for account_source |
list_applicant_comments | Comments about a candidate (log, defaults to type=COMMENT) |
add_applicant_comment | ✍️ Add a comment (write; editing/deletion is not available through the HuntFlow API) |
create_applicant | ✍️ Create a candidate card (write; first_name+last_name are required, resume as text/files; a repeat → duplicate, see doubles[]) |
attach_applicant_to_vacancy | ✍️ Attach a candidate to a vacancy and place them on a stage (write; vacancy+status are required) |
upload_resume | ✍️ Upload a resume file (write, multipart; file_path or content_base64; parse recognizes the CV) |
update_applicant_external | ✍️ Update an existing resume/external (write, PUT): source, text, files (by external_id) |
MCP prompts for typical recruiting scenarios:
| Prompt | Description |
|---|---|
skill-applicants | Candidates for a vacancy — a table with stages and a summary |
skill-vacancy-stats | Vacancy statistics — funnel, timing, conversion |
skill-vacancy-analytics | Analytics: days in progress, candidates at stages with the customer, timing for sending the CV to the client |
npm install
npm test # vitest (unit tests, mocked fetch)
npm run dev # tsx src/index.ts (run from TS without building)
npm run build # tsc → dist/
Structure: a thin HTTP client src/client.ts (Bearer + User-Agent, passing through API error bodies, retries only for GET), tools in src/tools/*.ts, server assembly in src/index.ts.
MIT. Based on theYahia/huntflow-mcp (MIT) with adaptations for the real HuntFlow v2 API.
Run Claude Code as an MCP server so any agent can delegate coding tasks to it
@microsoft✓ OfficialBrowser automation using accessibility snapshots instead of screenshots
@googleapis✓ OfficialGoogle's universal MCP server supporting PostgreSQL, MySQL, MongoDB, Redis, and 10+ databases
@github✓ OfficialOfficial GitHub integration for repos, issues, PRs, and CI/CD workflows