freehire MCP server

imageLightNow capabilities

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. The hosted plugin connects through OAuth; the local npm server authenticates with a personal API key. Postings are crawled straight from company career boards — 3.3M+ open roles across 294K companies, normalized into one schema and tagged with stack, seniority, region and work mode (live figures).

The local server mirrors the freehire CLI: same API, same credentials, exposed as MCP tools instead of shell commands.

Install

Hosted account connection (OAuth)

The plugin connects to https://freehire.me/api/v1/mcp/account over Streamable HTTP. Sign in to freehire and approve the OAuth connection in your host. It includes job search and market research, plus your profile, saved jobs, application tracking, reports, alerts and account-enabled automatic applications. In Claude Code, install it as a plugin:

/plugin install freehire --marketplace strelov1/freehire-mcp

In other OAuth-capable hosts, add the account URL as a custom remote connector and complete the sign-in flow. The included skill automatically submits the user's original unrecognized skill, specialization or company industry for dictionary review through suggest_dictionary_term. It also sends a minimal report_problem for a failed operation or missing capability, excluding credentials, CV content, conversations and personal contact details. These two workflow reports require no separate confirmation; empty search results alone trigger neither. The agent confirms submission only after success and continues the original task. Other account changes and application sending require your confirmation; automatic applications also require the account setting that permits connected agents to apply.

The ChatGPT package is freehire-account (display name Freehire Account), with a freehire-account MCP connection to the OAuth account endpoint. The existing published freehire plugin uses its original anonymous MCP URL; the portal does not allow changing that URL. Upload account-plugin updates to Freehire Account.

ChatGPT plugin and claude.ai skill downloads

Every push to main, pull request, and manual run of the CI workflow builds two ZIP files after the checks pass. Open a successful run and download the freehire-plugins-<commit> artifact:

• freehire-chatgpt-<version>.zip: upload this ZIP as the ChatGPT plugin package. It includes the portable plugin manifest, hosted MCP connection, icon, and the current find-tech-jobs skill.
• freehire-claude-skill-<version>.zip: upload this ZIP in claude.ai under Customize → Skills. Add https://freehire.me/api/v1/mcp/account as a remote connector separately and complete OAuth sign-in; uploading a skill does not configure an MCP connection.

Run npm run build:plugins locally to write both archives to dist/plugins/. Packaging uses Python 3.9+ and its standard library; it needs no API credentials, live server access, or sibling checkout. The version comes from package.json, and all packaged metadata, assets and skills come from the checked-out commit. Both archives include the same skills/find-tech-jobs/SKILL.md source and its dictionary and problem-reporting workflow. The hosted MCP connection discovers the live server's tools rather than bundling a fixed tool list; existing account tools remain available. This workflow builds download artifacts; directory submission and publication remain separate steps.

The hosted tools use names such as search_jobs, get_job, get_profile, save_job, track_job and my_jobs; discover their current schemas in your host. The hosted search accepts facet arrays inside filters. CV tailoring and experience bank tools in the local server below are not part of this account connection.

Local server (npm)

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.me → 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.

Local server authentication

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

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.

Local server 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, exclude_skill, 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.

Geography widens. region, country and city are ONE OR-group: region: ["eu"] with country: ["IT"] means "in Europe or in Italy" and returns everything the region alone would. To search a single country, pass country and omit region. The three name a single concept — where — so picking two places reads as "either", which is what makes region: ["eu"] with country: ["BR"] ("Europe or Brazil") useful. There is no AND to switch on: _mode=and does not apply to geography.

Unknown values are named, not guessed. A filter value the API does not recognise (a misspelt skill such as golangg) is reported in ignored_values, e.g. {"skills": ["golangg"]}, beside total in search and in the {data, ignored_values} wrapper of facets and market_fit. Unlike an unread param it still narrows — to nothing — so a 0 beside it is a typo, not an empty market. Skill aliases resolve server-side (golang searches go); list_filter_values names the real value.

Unread params are ignored, not refused. A filter key the API does not recognize does not fail the request, it widens it. Such keys come back in the result's ignored list, with did_you_mean when only the grammatical number was wrong. search reports it alongside total; facets and market_fit answer a single object, so they wrap it as {data, ignored} — and only then, leaving a clean call's shape untouched. Any number from a result carrying ignored answers a broader question than the one asked — retry with the suggested name before reporting it.

Forwarded tools. check_jobs_open, similar_jobs, salary_stats, job_market_stats and list_filter_values have no REST route, so they are forwarded to freehire's anonymous hosted MCP server (/api/v1/mcp, no key sent). The five job-alert tools are forwarded to the signed-in one (/api/v1/mcp/account) with your API key, so an alert made here is exactly the website's — the same saved search, channel rule and match ledger, not a second implementation of them. Their answers arrive in the hosted server's own words. Automatic applications (auto_apply_*) stay on the OAuth-signed-in endpoint and are not offered to an API key.

Searching well. Join a role's two or three names with an uppercase OR (title:SRE OR title:"site reliability"), put location, work mode, seniority and skills in filters rather than the query, loosen one constraint at a time when few results come back, shortlist from the search results and run check_jobs_open before presenting.

Descriptions. search reads the API's agent endpoint, so every hit already carries the posting's full description rendered as markdown — a host can screen a result set without a job call per hit. Descriptions are long, so keep limit modest.

The evidence rule. Every achievement in the bank records who asserted it. cv_import, stated_in_chat and manual mean the candidate did, and may be cited on a CV; agent_inferred means a model read it into the record, and may not. cv_edit refuses any claim about the candidate without an evidence_id pointing at a citable one, which is why experience_list is the tool that makes cv_edit usable at all.

Correcting an achievement does not move that label: an agent_inferred one stays uncitable however it is reworded. The only way it becomes citable is to ask the candidate, then record what they say with experience_add_achievement.

Removing is final — the bank has no undo. A place must be emptied before it can go, because deleting one would take every achievement under it. Folding two achievements into one, keeping the numbers from both, is on the site.

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.