Huntflow

MCP server for HuntFlow ATS API v2 — vacancies, candidates, resumes, funnel stages, rejection reasons, comments, accounts. 16 tools, 3 prompts.

npm License: MIT

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

Tools (16)

Prompts (3)

MCP prompts for typical recruiting scenarios:

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.