freehire MCP server

An MCP server over the freehire job API. It lets any MCP host — Claude Desktop, Claude Code, or a compatible agent — search, filter, and apply to IT jobs without a browser, authenticating with a personal API key. It mirrors the freehire CLI: same API, same credentials, exposed as MCP tools instead of shell commands.

Install

No global install needed — the host runs it via npx. Add it to your host's MCP configuration (Claude Desktop → Settings → Developer → Edit config, or ~/.claude.json for Claude Code):

{
  "mcpServers": {
    "freehire": {
      "command": "npx",
      "args": ["-y", "freehire-mcp"],
      "env": { "FREEHIRE_TOKEN": "fhk_xxxxxxxx" }
    }
  }
}

Create the fhk_… key in the web app (freehire.dev → account menu → API keys). If you already use the freehire CLI (freehire auth login), you can omit env — the server reads the same ~/.freehire/creds.json.

Related MCP server: MCP Resume & Email Assistant

Authentication

The token and API base URL resolve with precedence env → ~/.freehire/creds.json → default https://freehire.dev:

The server only reads the credentials file (it never writes it — logging in stays the CLI's job). If no token is configured, tools return a clear "not authenticated" error rather than the server failing to start.

Tools

Filters. search, market_fit, and facets share the same market-filter parameters: remote, region, country, city, company, category, role, seniority, employment_type, english_level, salary_min, visa, plus a generic facets map ({"source": "greenhouse"}) for any other facet in the vocabulary. Discover valid values with the facets tool — do not invent them. In search, skills is a filter; in market_fit, skills is the measured set.

Each tool returns the raw API data as JSON text; an API error becomes an isError result carrying the HTTP status (a 401 adds an auth hint).

Develop

npm install
npm test        # vitest: config, client (mock server), facets, tool dispatch
npm run build   # tsc → dist/

License

MIT — see LICENSE. The freehire backend and CLI are MIT too.