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.

Installation

🧑‍💼 Not a programmer? There is a step-by-step guide in plain language: INSTALL.md

Via npx — Claude Desktop (recommended)

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).

From source (for development)

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"].

Streamable HTTP

HUNTFLOW_TOKEN=your-token node dist/index.js --http
# POST /mcp, GET /health on port 3000 (override with PORT=...)

Getting a token

1. In HuntFlow: Settings → API → Add token.
2. The system will issue a link like 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.
3. Put the resulting access_token (a long string) into HUNTFLOW_TOKEN.

The access_token lives for 7 days, the refresh_token for 14. The server does not refresh the token automatically — once it expires, obtain a new token again.

Environment variables

| 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) |

Tools (16)

| 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) |

Prompts (3)

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 |

Development

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.

License

MIT. Based on theYahia/huntflow-mcp (MIT) with adaptations for the real HuntFlow v2 API.