Claude Works
This MCP server turns a job-search pipeline into typed tools for discovery, fit scoring, resume gating, submission planning, and application tracking.
Discover and rank fresh jobs from public ATS boards or offline demo data, de-duped by role.
Fetch plain-text job descriptions from Ashby, Greenhouse, and Lever URLs for sharper scoring.
Score roles 0–10 against a fit rubric with hard caps that force honest pursue verdicts.
Curate the queue by keeping and fit-ranking real matches while parking others with auditable reasons.
Look up and list search angles/lenses to bias discovery and scoring.
List verified resume claim fragments from the claims bank.
Build tailored resumes from verified fragments and run static lint/anti-fabrication gates.
Render resumes to PDF and check the one-page gate.
Verify any resume HTML against style and anti-fabrication gates.
Build deterministic fill-and-park submission plans with ATS-specific gotchas; no browser is driven.
Read recent ATS email verification codes via scoped, read-only IMAP when authorized.
Append and list application ledger rows, de-duped by company and role, with status summaries.
List and inspect the discovery queue by status to enforce queue-first operation.
Uses IMAP to read ATS email verification codes from the user's Gmail inbox for email-ownership verification during application submission.
Integrates with Greenhouse's public posting API to discover jobs, fetch job descriptions, and support auto-submission for application pipelines.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Claude Works discover latest backend jobs in my area"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Claude Works
An MCP server that turns a perpetual, fit-first job-application pipeline into typed, honest tools an LLM agent can call.
What it is
Claude Works is a Model Context Protocol server built on the official MCP Python SDK (MCPServer, formerly FastMCP; both the 1.x and 2.x SDKs are supported). It exposes a working, autonomous job-application loop (discovery sweeps, fit scoring, a verified resume builder, a fill-and-park submission planner, and an application ledger) as a small set of typed tools.
The point is not to wrap a chatbot around a job board. The point is to put the policy where it cannot drift: in code. An agent calling these tools cannot quietly inflate a fit score, claim a resume passed gates it never ran, or report a submission that did not happen. The honesty lives in the modules, not in a system prompt that the next conversation might forget.
The core (everything except the MCP server wiring) imports with the standard library only. That keeps the domain logic fast to test, easy to read, and reusable outside the MCP runtime.
Related MCP server: job-search-mcp
Try it in two minutes
The repo ships a demo mode: sanitized sample data for a fictional persona, shaped exactly like the private production files, so every tool works from a fresh clone with zero network access.
git clone https://github.com/andrewaws26/claude-works.git
cd claude-works
pip install -e .
claude mcp add claude-works \
-e JOBSEARCH_DATA_DIR="$PWD/examples" \
-e JOBSEARCH_RESUMES_DIR="$PWD/examples/resumes" \
-- python -m claude_worksThen ask Claude to score a role. This is what "honesty in the modules" looks like on the wire; the agent cannot argue with it:
// score_job(title="Principal Engineer, ML Infrastructure", company="Massive Scale Co", ...)
{
"value": 5.0,
"pursue": false,
"reasons": ["hard cap: over-level title ('principal')"],
"hard_cap": "over-level title ('principal')"
}
// score_job(title="Forward Deployed Engineer", ..., jd_text="...agentic workflows on
// Claude with MCP tools, own evals, ... first technical hire.")
{
"value": 8.5,
"pursue": true,
"reasons": [
"core-stack overlap: agent, agentic, claude, eval, mcp (+4.0)",
"rare-edge match: forward deployed (+1.0)",
"level fit: mid / IC / first-hire (+2.0)",
"clean channel: Ashby/Greenhouse autonomous-submit (+1.0)",
"remote (+0.5)"
],
"hard_cap": null
}The examples README walks through the rest: the offline demo discovery source, queue curation with auditable park reasons, and the resume gates (try sneaking "Holds a PhD" into the demo persona's summary and watch verify_ok flip to false).
Architecture

The system is a five-stage pipeline. Each stage is a frozen or plain @dataclass defined in models.py, and each crosses the MCP boundary as a JSON-serializable dict:
SearchAngle -> Job -> Score -> Resume -> ApplicationSearchAngle is one reusable search lens (FDE, IoT, and so on). It biases discovery and scoring toward a lane without changing the rules.
Job is a single discovered role, normalized across every source. Its
role_key(ATS plus org slug plus job id, parsed from the apply URL) is the canonical identity used for de-duplication. De-dup is by role, never by company, so the same company with a different role is allowed.Score is the fit-rubric verdict for a job: a value from 0 to 10, a
pursueboolean, one reason line per signal, and ahard_capfield set when a disqualifying signal applies.Resume is a built artifact plus the verdicts of a four-gate verification pipeline (one-page render, style lint, anti-fabrication verify, and an agent claim-trace check).
Application is one row in the durable ledger.
Module layout:
Module | Responsibility |
| The five dataclasses, the de-dup |
| Paths, the comp floor, the rails (exclusions, over-level terms, hard-gap skills), and environment-only credential reads. |
| Source sweeps, search-angle parsing, and the scoring function with its hard caps. |
| Queue triage: park poor-fit roles (off-lane, over-level, non-US, excluded, hard-skill-gap, already-applied) with an auditable reason, and fit-rank the rest so the loop applies to the strongest open match first instead of whatever is next in line. |
| The resume builder and the static verification gates. |
| ATS classification and the deterministic fill-and-park plan builder. |
| Reading and appending the ledger and the discovery queue, de-duped by role. |
| The MCP server wiring. The only module that imports |
Because __init__.py imports only models, import claude_works never requires the MCP runtime, and the unit tests run against the pure core with no network and no third-party dependencies.
Tools
Every tool returns JSON-serializable structures so results flow straight back into the model.
Tool | Contract |
| Find fresh roles, ranked by fit and de-duped by role. The default |
| Pull a posting's title, location, and plain-text JD from its ATS URL (headless, via the public posting APIs), so |
| Triage the discovery queue: keep and fit-rank the genuine fits, park the rest with an auditable reason. Nothing is discarded. |
| Score one role 0 to 10 against the fit rubric and return the pursue verdict (with any hard cap). |
| Read the newest ATS emailed-verification code from the applicant's own inbox (scoped, read-only IMAP): email-ownership verification, never captchas. |
| Look up one search lens by name or trigger, or the default lane when the name is empty. |
| List every defined search lens (name, trigger, definition). |
| List the verified resume building blocks (roles, bullets, projects) that trace to the claims bank. |
| Build a tailored one-page resume from verified fragments and run the static gates. |
| Render a resume to PDF and report whether it is exactly one page. |
| Run the two static gates (style lint plus anti-fabrication verify) on any resume HTML. |
| Build the fill-and-park submission plan for a role (no browser is driven here). |
| Append one row to the ledger, de-duped by company and role. |
| List roles in the discovery queue by queue status (the queue-first gate). |
| List ledger rows, optionally filtered by status. |
| Return a count of ledger rows by status. |
Install
git clone https://github.com/andrewaws26/claude-works.git
cd claude-works
pip install -e ".[dev]"Run the checks CI runs (no network needed):
ruff check . && mypy && pytestQuickstart
Start the server over stdio:
python -m claude_worksRegister it with Claude Desktop or Claude Code by adding it to your MCP server config:
{
"mcpServers": {
"claude-works": {
"command": "python",
"args": ["-m", "claude_works"],
"env": {
"JOBSEARCH_APPLY_NAME": "Your Name",
"JOBSEARCH_APPLY_EMAIL": "you@example.com",
"JOBSEARCH_APPLY_LOCATION": "City, ST",
"JOBSEARCH_COMP_FLOOR": "120000",
"JOBSEARCH_PURSUE_THRESHOLD": "7.0"
}
}
}
}Configuration
All configuration is environment driven. Nothing sensitive is stored in the repo.
Variable | Purpose |
| Directory holding the ledger, queue, and policy documents. Defaults to the package parent. Readers degrade gracefully when files are absent. |
| Directory holding the resume generator and render pipeline. |
| Base compensation floor in USD per year. |
| The 0 to 10 score at or above which a role is pursued. |
| Identity and contact fields, read at submission time only. No PII of any kind is hard-coded in the repo; an unset field is omitted from the plan. |
| Profile links for application forms, read the same way. |
| Portal credentials, read from the environment only and never stored. A missing credential fails loudly instead of silently mis-filling a form. |
| Optional, for |
Running it for your own search
The defaults encode one candidate's policy: his excluded companies (active interview tracks), his skill gaps, his scoring vocabulary. None of that transfers, so none of it requires editing code to change. Drop a policy.json next to your trackers (in JOBSEARCH_DATA_DIR) and any key you define replaces the corresponding default wholesale; examples/policy.sample.json shows every supported key:
Key | Controls |
| The comp floor and the 0-10 pursue gate (env vars still win). |
| Skills you lack that, when hard-required, disqualify a role. |
| What counts as over-level vs level-fit for you. |
| Rails: domains you refuse and companies you must not (re-)apply to. |
| Your scoring vocabulary: daily-stack terms and rare-differentiator terms. |
| Curation's title lanes and what gets parked as off-lane. |
A policy file that exists but does not parse fails loudly at import; running silently on someone else's exclusion list is exactly the kind of quiet wrongness this codebase refuses.
The fastest path: clone the repo, open Claude Code, type /setup. The bundled command interviews you for example jobs you want and your resume, then derives all of the below from those examples (policy, search angles, seed boards, resume fragments), registers the MCP stack, and smoke-tests the pipeline before handing it over.
What the personalization consists of (all derivable by /setup, all editable by hand):
Identity: the
JOBSEARCH_APPLY_*environment variables (name, contact, profile links, portal credentials). Nothing personal is in the repo.A queue and ledger: start with empty files;
record_applicationcreates the ledger on first append.Search angles: your own
SEARCH_ANGLES.md(the demo one shows the format).Resume fragments: the resume tools drive a claims-bank generator; copy
examples/resumes/_genlib.pyand replace the fragments with claims that are true of you. The gates then hold you to them.Discovery: the built-in
boardssource works out of the box over yourseed_boardsorgs. Thenewsource/board_harvestsources wrap private harvest scripts not in this repo and fail loudly without them.
The full agent stack
This package is the policy brain. A complete, working system is three MCP servers plus the playbooks in this repo:
claude mcp add claude-works -e JOBSEARCH_DATA_DIR=... -- claude-works # scoring, curation, plans, gates, ledger
claude mcp add playwright -- npx @playwright/mcp@latest # executes the submission plans in a real browser
claude mcp add --transport http jobdatalake https://mcp.jobdatalake.com # optional: 1M+ indexed roles, free tier, wide-net discoveryThe division of labor: discovery comes from the built-in boards source and/or JobDataLake's search_jobs; every candidate role goes through fetch_job_description and score_job; curate_queue picks the strongest open fit; build_resume/render_resume/verify_resume produce a gated one-pager; submit_application emits the deterministic plan; the agent executes that plan with Playwright following PLAYBOOK.md (every hard-won per-ATS lesson, sanitized); the real outcome lands in the ledger via record_application. OPERATING.md is the loop's operating model: queue-first, honest walls, de-dup semantics, and the standing self-improvement mandate.
Design principles
Honesty is enforced in the modules, not the prompt. Three concrete mechanisms:
Score hard caps. An over-level title (Director, Principal, Staff, and the like), a required-skill gap, a non-US-only role, an excluded domain (defense, surveillance, and so on), or an active interview track caps the score and forces
pursue=False. The agent cannot score its way past a disqualifier.Gate findings, not claims. The resume tools return the actual results of the lint and anti-fabrication gates with the specific findings attached. A resume is reported as passing only when every automated gate ran and passed.
Fill-and-park plans, not faked submits.
submit_applicationreturns a deterministic plan (the ATS, the action, the field values, the honest screening answers, and the one human step left when parked). It never drives a browser and never reports a submission that did not happen. The real outcome is recorded afterward throughrecord_application.
A self-improving ATS playbook. submission.py carries an ATS_GOTCHAS table: hard-won, per-ATS form-handling tactics (Ashby labeled-radio focus-plus-Space, Lever's hidden resume input behind an hCaptcha, Workable masked-date sequential typing, Hirebridge's ASP.NET postback cascade and FormValidation-gated submit, and so on). Every plan carries the relevant tactics so the browsing agent does not relearn them each run. When a better way to fill or submit a form is found, it is appended here and committed, so the knowledge persists across instances the way a person remembers a shortcut.
Typed dataclass boundaries. Every value that crosses a tool boundary is one of the five core dataclasses with an explicit to_dict. The schema is the contract, and the contract is the same whether a record was written by this server or by the underlying loop. The package ships a py.typed marker, and CI type-checks it with mypy.
A ledger that survives concurrency. Parallel loop instances share one applications.json. Every append holds an exclusive lock for the whole read-modify-write and lands via an atomic temp-file replace, so concurrent writers cannot drop each other's rows and a crash mid-write cannot corrupt the file. De-dup runs on the (company, role) pair and on the canonical role_key parsed from the apply URL, which catches the same role re-entering under a differently spelled company name.
Zero-dependency, testable core. The domain logic depends on nothing but the standard library. The tests cover the slug and role-key normalization, the dataclass round-trips, the de-dup-by-role behavior, the scoring hard caps, the curation park reasons, the submission planner, the demo fixtures, and the server's tool registry, all without touching the network. CI runs ruff, mypy, and pytest on Python 3.10 through 3.13.
License
MIT. See LICENSE.
Available Tools
16 toolsbuild_resumeA
Build a tailored one-page resume from verified fragments and run the static gates.
Args: name: output file stem (becomes ".html" in the resumes dir). tagline: the header tagline (mid-level; no over-level words). summary: the summary paragraph. experience: list of [role_key, [bullet, ...]] where role_key is one of bnb / twinspires / upwork / humana / tesla / dojo / lifespring, and each bullet is a fragment NAME (e.g. "BNB_AI") or text tracing to CLAIMS_BANK. projects: list of project fragment names (e.g. "P_CASEK") or verified HTML. skills: list of [label, text] rows for the Skills block.
Returns the resume with lint_ok / verify_ok and any findings. The 1-page render gate runs separately via render_resume (it needs Chrome).
Inputs: name (required), skills (required), summary (required), tagline (required), +2 more. Returns: object
curate_queueA
Triage the discovery queue into a fit-ranked active set and a parked set.
Runs the curation pass over up to limit queue entries with the given queue
status: every job is either KEPT with a fit score (active, ranked best-match
first, so the loop applies to the strongest open role next) or PARKED with an
auditable reason (off-lane, over-level, non-US, onsite-hybrid, model-training,
excluded, already-applied, hard-skill-gap, ...). Already-applied detection uses
the ledger's company and ATS-org slugs. Nothing is discarded; parked roles keep
their reason so a human can review or restore them. Returns {active, parked,
counts}.
Inputs: limit, status. Returns: object
discover_jobsA
Find fresh roles from a discovery source, ranked by fit, de-duped by role.
Args: angle: a search lens from SEARCH_ANGLES.md (e.g. "FDE", "IoT") to bias ranking toward that lane. Empty = the default lane. source: which sweep to run. "boards" (default) queries the public Ashby/Greenhouse/Lever posting APIs over the seed_boards org list in policy.json and works from a bare install. "demo" returns canned fictional roles offline. "newsource"/"getro"/"anthropic"/ "board_harvest" wrap private harvest scripts in the data dir and fail loudly when absent. For a much wider net, pair this with the JobDataLake MCP (search_jobs) and feed its results to score_job. limit: max roles to return.
Returns a list of job dicts (title, company, url, source, location, remote, ats, role_key). Roles the rails hard-cap always rank below clean ones.
Inputs: angle, limit, source. Returns: result
fetch_job_descriptionA
Fetch a posting's title, location, and plain-text JD from its ATS URL.
Supports Ashby, Greenhouse, and Lever job URLs via their public posting APIs (the same ones the boards sweep uses). Use the returned text as score_job's jd_text: titles under- and over-sell, so scoring on the JD is sharper, and the body is the only reliable place to catch in-office requirements hiding behind a remote flag. Returns {error} when the URL is unrecognized or the org disabled its public API (a board 404 does NOT mean the role closed; check the live page before recording it closed).
Inputs: url (required). Returns: object
fetch_verification_codeA
Read the newest ATS email-verification code from the applicant's own inbox.
For the emailed-code gate some ATSes put in front of the final submit: this is email-OWNERSHIP verification of the applicant's own application, which the applicant has authorized, NOT a captcha. Scoped and read-only: only recent mail from known ATS sender domains is considered, via IMAP BODY.PEEK with a revocable app password from the environment. Returns {status, code?}. NO_CODE_FOUND right after submit usually means the mail is in transit; wait ~8s and retry (up to 3x) before parking. Never use this reasoning for captchas or no-AI attestations: those always park for the human.
Inputs: minutes. Returns: object
get_search_angleA
Look up one search angle (lens) by name or trigger from SEARCH_ANGLES.md.
Empty name returns the default (FDE / converting-profile) lane. Returns the angle's name, trigger phrase, definition, and target titles, or null if no angle matches.
Inputs: name. Returns: result
ledger_summaryA
Return a count of ledger rows by status (a one-glance system summary).
Inputs: no named parameters. Returns: object
list_applicationsA
List ledger rows, optionally filtered by status. Empty status = all rows.
Inputs: status. Returns: result
list_claim_fragmentsA
List the verified resume building blocks from _genlib.py (roles, bullets, projects).
Every fragment traces to CLAIMS_BANK.md. Build resumes only from these names (or text that traces to the claims bank); this is what keeps the output honest.
Inputs: no named parameters. Returns: object
list_queueA
List roles in the discovery queue (top300_jobs.json) by queue status.
Status is the queue's own field ("todo" by default). Returns up to limit
job dicts. Use this to apply from the existing queue before running new
discovery (the queue-first gate).
Inputs: limit, status. Returns: result
list_search_anglesA
List every search angle defined in SEARCH_ANGLES.md (name, trigger, definition).
Inputs: no named parameters. Returns: result
record_applicationA
Append one row to the application ledger (applications.json), de-duped by role.
Status mirrors the existing vocabulary ("submitted", "submitted-verified", "deferred-captcha", "skipped-overlevel", ...). Date defaults to today. Returns whether it was recorded (false if this company+role is already logged) and the new total.
Inputs: role (required), company (required), ats, note, +3 more. Returns: object
render_resumeA
Render .html to PDF via _render.sh and report whether it is one page.
Returns the resume with one_page set and the pdf_path. Requires Google Chrome and qpdf. This is the first of the 4 gates.
Inputs: name (required). Returns: object
score_jobA
Score one role 0-10 against FIT_RUBRIC.md and return the pursue verdict.
Pass the JD text when available; titles under- and over-sell, so scoring on the JD is sharper. Returns value (0-10), pursue (bool, >= threshold and no hard cap), reasons (one line per signal), and hard_cap (set when a required-skill gap, over-level title, non-US-only, or excluded domain/company disqualifies it).
Inputs: title (required), url, angle, company, +2 more. Returns: object
submit_applicationA
Build the fill-and-park submission plan for a role (no browser is driven here).
Returns a plan an agent executes with the Playwright MCP: the ATS, the action ("auto_submit" for Ashby/Greenhouse, "fill_and_park" for Lever/Workday/captcha walls, or "blocked" for a rail violation), the standard field values and honest screening answers, the single human_step left when parked, and ATS-specific gotcha notes. Identity PII and credentials are read from the environment, never stored. Report the real outcome afterward with record_application.
Inputs: url (required), title (required), company (required), ats, +2 more. Returns: object
verify_resumeA
Run the two static gates (lint + anti-fabrication verify) on a resume HTML.
Use this to check any resume on disk. Returns lint_ok, verify_ok, passed (their AND), and findings: every blocklist hit (C/C++, fabricated employer, model over-claim, ...) and style flag (banned words, em dashes, rule-of-three).
Inputs: path (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each tool maps to a distinct stage or resource in the workflow: discovery, JD fetch, scoring, queue curation, resume build/verify/render, submission planning, and ledger read/write. Closely related tools like get_search_angle vs list_search_angles and discover_jobs vs list_queue are separated by lookup-vs-enumerate and new-discovery-vs-existing-queue.
Nearly all tools follow a clear verb_noun pattern using predictable verbs like list_, get_, fetch_, build_, render_, and record_. The only notable outlier is ledger_summary, which is a noun phrase rather than a verb-led name, but the overall convention is consistent and readable.
At 16 tools, the set is slightly above the typical 3-15 well-scoped range, but the count is justified by the breadth of an end-to-end job-search pipeline. Each tool covers a distinct step with little redundancy, so the size feels earned rather than bloated.
The surface covers the full core loop: discovery, curation, scoring, resume building/verification/rendering, submission planning, email verification, and application ledger recording. Minor lifecycle gaps exist, such as updating or withdrawing ledger entries and programmatically restoring parked roles, but these do not block the main workflow.
Maintenance
Related MCP Connectors
Public MCP server for discovering open jobs. Search, filter, and get application links.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA local-first, open-source MCP server that analyzes jobs, matches your CV, tailors documents, and tracks applications — all on your machine with no data uploaded.AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceAn MCP server that exposes job-search and application-management capabilities to compatible AI clients, enabling discovery of vacancies, drafting of tailored application materials, and coordinated human-approved submissions.MIT
- AlicenseAqualityDmaintenanceA privacy-first MCP server for locally managing job, fellowship, and graduate-school applications. It offers tools for tracking application status, analyzing role fit, generating LaTeX CV/cover letters, interview prep, and discovering public jobs from ATS APIs.81MIT
- AlicenseAqualityBmaintenanceAn MCP server that automates job applications by discovering postings from ATS boards, applying eligibility gates, scoring candidates, and drafting answers, while requiring human approval before submission. It respects anti-bot controls and only submits with explicit consent.222MIT