Freehire

What freehire MCP server does

freehire exposes the freehire job API through MCP. It covers a large normalized catalogue of IT vacancies gathered from company career boards, along with tools for searching, inspecting, and managing opportunities. Authenticated users can mark jobs as applied, save or unsave them, set application stages, add notes, and list tracked vacancies.

The server also supports vacancy-specific CV work. An agent can create or reopen a tailored CV, inspect the fit-analysis context, read the full document, apply validated edits, and render the result as an ATS PDF. A separate experience bank stores employment records and candidate-provided achievements, including provenance that determines whether an item can be cited in a CV.

How it works

Authentication uses a freehire API key. Call whoami first to verify the key before using authenticated operations. The local server reads FREEHIRE_TOKEN, or falls back to credentials stored by the freehire CLI at ~/.freehire/creds.json. The API base URL defaults to https://freehire.me and can be overridden with FREEHIRE_API_URL.

Start discovery with facets. It returns live filter values, vacancy counts, skills, and numeric ranges. Use those values with search or market_fit rather than guessing filter names or values. Search results include full job descriptions in markdown, so an agent can screen results without fetching each job separately. A returned public slug identifies the vacancy for tools such as job, apply, save, and CV operations.

Geographic filters for region, country, and city are combined as one OR group. Passing a region and a country broadens the search instead of narrowing it. Unsupported filter keys are ignored and reported; retry with any suggested name before using a returned total or market-fit figure.

Setup and configuration

The package can run locally through npx, without a global installation. Add an MCP server entry that runs npx -y freehire-mcp and provide the API key through FREEHIRE_TOKEN. If the freehire CLI has already authenticated the user, the server can reuse its credentials file instead of receiving the token in the MCP configuration.

A hosted, read-only Streamable HTTP endpoint is available at https://freehire.me/api/v1/mcp. Claude Code can install it through the freehire plugin marketplace, while other MCP hosts can add the URL as a custom remote connector. The hosted endpoint is intended for job-search tools; local configuration is the route for the broader authenticated workflow.

Tools and capabilities

• Discover live facets and search open jobs with keyword and market filters.
• Measure skill coverage and identify missing skills associated with more vacancies through market_fit.
• Fetch complete job or company records, including posting descriptions and open company jobs.
• Track applications with apply, stage, note, my, save, and unsave.
• Create, inspect, edit, and render tailored CVs with cv_tailor, cv_context, cv_get, cv_edit, cv_render, and cv_list.
• Maintain candidate evidence with employment and achievement add, update, list, and removal tools.
• Submit vacancies for moderation and, for moderator accounts, create or edit manual jobs and review pending submissions.

CV editing is deliberately constrained. Read cv_context and cv_get before editing, use evidence IDs from experience_list for claims about what the candidate did, and distinguish existing evidence from gaps that require asking the candidate. Edits are atomic: one invalid path or uncited claim rejects the whole batch. Removing experience has no undo, and an employment record must be empty before it can be removed.