job-search-mcp

An MCP server for job hunting under a visa constraint.

If you need sponsorship, most job search tooling answers the wrong question. It tells you a role exists. It does not tell you whether the employer can legally hire you, or whether the "mid-level" title is hiding a senior brief, or that the company posting the role is a recruitment agency that holds no licence at all.

This server answers those questions. It exposes four tools over the Model Context Protocol so an AI assistant can check them itself instead of guessing.

Tools

Tool	Answers
check_sponsor	Does this employer hold a UK Skilled Worker licence, and how much can I trust the match?
screen_posting	Are there hard bars here? Is the title telling the truth about seniority?
search_roles	What is live right now, minus the agencies?
application_history	Have I already applied here?

Why confidence grading exists

The obvious way to check a sponsor licence is to search the register for the company name. That is how this started, and it is wrong often enough to be dangerous.

Company names collide. To match Pimberly against its registered name Pimberly Software Development Limited, you have to strip words like "Software" and "Limited". That same normalisation turns Minerva Defence into minerva, which matches thirteen unrelated companies: a furnishing business, a credit agency, a supported-living provider.

So check_sponsor returns a confidence grade rather than a boolean:

• high — the distinctive part of the name matched exactly, once.
• verify — something matched, but it could be coincidence. Confirm the employer's registered legal entity, then look that name up.
• none — nothing matched. This is not proof they cannot sponsor. Many licensed employers trade under a name unlike their registered one.

Real cases that shaped this:

Searched	Matched	What was true
Minerva Defence	13 unrelated "Minerva" rows	MINERVA DEFENCE LTD is not on the register, nor its former name PARABELLUM TECHNOLOGIES LTD
Prevail	Prevail Technology Limited (Poole)	The employer is Prevail Partners Ltd, which is absent. Same town, different company
MAGIC	MAGIC SOFTWARE SERVICES LTD	Right answer, wrong evidence. The employer is MAGIC TECH LTD, also licensed
TransPerfect	PERFECT DIGITAL LTD	Matched on the word "perfect"
eFinancialCareers	eFinancialCareers Ltd	Correct and useless: licensed, but a job board. Roles under its name belong to unnamed third parties

Why screen_posting reads the body, not the title

A posting titled "Software Engineer" opened with "As a Senior Software Engineer you will" and asked for someone to join "the founding team". Another titled "Software Engineer (Java Mid)" named a senior grade three paragraphs down. Title-based filtering misses both.

screen_posting also catches hard bars that no amount of tailoring survives:

You must be a UK citizen and have lived in the UK for the past 10 years.
You must already hold high-level UK security clearance.

and the one that matters most when you need sponsorship, from a company that holds an A-rated licence:

We are unable to offer visa sponsorship for this role. Candidates who need visa
sponsorship now or will need it in the future will not be considered.

A licence means a company can sponsor. It does not mean it will.

Why search_roles returns a funnel

UK job boards are dominated by recruitment agencies, and an agency does not hold the sponsor licence for a role it advertises. Filtering them out is essential and brutal: a typical search drops from seven results to one.

One result with no explanation looks like a bug. So the tool returns what each stage removed:

{
  "totalFromSource": 7,
  "funnel": { "fromSource": 7, "afterAgencyFilter": 2, "afterSalaryAndAge": 1 },
  "notes": ["5 of 7 results were recruitment agencies or job boards. ..."]
}

Unpublished salaries are kept, never filtered out. Silence about pay is not evidence of low pay.

Install

npm install && npm run build

Download the current register (about 11 MB, updated regularly):

https://www.gov.uk/government/publications/register-of-licensed-sponsors-workers

Save it as data/register.csv, or point SPONSOR_REGISTER_PATH at it.

Claude Desktop / Claude Code

{
  "mcpServers": {
    "job-search": {
      "command": "node",
      "args": ["/absolute/path/to/job-search-mcp/dist/index.js"],
      "env": {
        "SPONSOR_REGISTER_PATH": "/absolute/path/to/data/register.csv",
        "REED_API_KEY_FILE": "/absolute/path/to/.reed-api-key"
      }
    }
  }
}

Variable	Required	Purpose
SPONSOR_REGISTER_PATH	no	Register CSV. Defaults to ./data/register.csv
REED_API_KEY_FILE	for search_roles	Path to a file containing the key. Preferred: the secret lives in one place and the client config holds only a path
REED_API_KEY	alternative	The key inline. Simpler, but copies the secret into your MCP config
APPLICATION_LEDGER_PATH	no	NDJSON application history

No credential is ever read from a file inside the repo, and the register is gitignored.

Or with the Claude Code CLI:

claude mcp add job-search --scope user \
  --env SPONSOR_REGISTER_PATH=/path/to/data/register.csv \
  --env REED_API_KEY_FILE=/path/to/.reed-api-key \
  -- node /path/to/job-search-mcp/dist/index.js

Tests

npm test

54 tests. Every fixture is a real posting or a real register entry that defeated an earlier version of this code. The Reed tests mock fetch, so the suite runs offline and costs no API quota.

Two bugs the suite caught while it was being written:

• £40,000-85,000 parsed as a flat £40,000, because the second figure omits the currency symbol. Against a salary threshold, that is the difference between "clears it" and "does not".
• An agency filter written as \brecruit\b never matched Recruitment or Consultancy. Roughly fifty agencies passed straight through.

Design notes

core() deliberately destroys information. Stripping descriptors is what makes brand-to-legal-name matching work, and it is exactly what causes false positives. The confidence grade prices that trade-off instead of hiding it.

Absence is not a negative. none carries a caveat saying so. The costliest error in this domain is concluding that an unlisted employer cannot sponsor.

Read-only. The server reads the application ledger; it never writes to it. Recording an outcome is a decision a person should make.

Licence

MIT