job-apply-mcp (ApplyWise)

An MCP server that finds jobs and fills applications for you, and stops before anything irreversible. It is modular (pluggable platforms, LLM providers, browser drivers), parallel, token-frugal (compact, paginated output) and local-first (routine form fields go to Ollama, LM Studio or MLX on your machine; only hard prose escalates). Works with any MCP client on macOS, Linux and Windows.

Install as a Claude Code plugin

The repository is also a Claude Code plugin marketplace. The applywise plugin starts the MCP server for you (pinned to a reviewed version) and adds a skill that tells Claude how to use the tools safely:

claude plugin marketplace add tanmayagrawal21/job-apply-mcp
claude plugin install applywise@applywise

Then run init and doctor from the quickstart below in your own terminal, and check /mcp for plugin:applywise:applywise. The same safety model applies: dry run by default, a human approves every real submit, and visible CAPTCHAs always come back to you; logins, codes and account creation stay with you unless you open a consent window yourself (safety model, items 7 and 8). To update, run claude plugin update applywise@applywise. How releases and the version pin work: docs/release.md.

5-minute quickstart

You need uv (or pipx). No clone required.

# 1. Create config.toml, profile.toml, controls.toml (asks a few questions; --yes to skip them)
uvx --from git+https://github.com/tanmayagrawal21/job-apply-mcp job-apply-mcp init

# 2. Put your real details in the profile it printed the path of, then check everything
uvx --from git+https://github.com/tanmayagrawal21/job-apply-mcp job-apply-mcp doctor

# 3. Add the printed snippet to your MCP client (guides for ten clients: docs/clients/)
claude mcp add --transport stdio job-apply -- uvx --from git+https://github.com/tanmayagrawal21/job-apply-mcp job-apply-mcp

Then ask your assistant: "search jobs at greenhouse:examplecorp for data roles, plan the best one, and do a dry run." Everything is a dry run until you set dry_run = false.

Install alternatives: pipx install git+https://github.com/tanmayagrawal21/job-apply-mcp (then the command is just job-apply-mcp), or pip install into a virtualenv. After the first PyPI release, uvx applywise (the PyPI distribution is applywise; the job-apply-mcp command stays as an alias). Optional extras: [browser] (Playwright), [agent], [jobspy], [mlx], [hf], [litellm], [keyring].

Features

Run statuses

Every posting in a run_applications / run_report result has exactly one status, with a why where useful (ADR-0049):

max_applications (a whole number >= 1) caps the eligible postings a run handles (ready to submit, or needing you), the same in dry and live mode; skipped and unsupported postings do not count. A dry run also returns live_preview with what the current live quotas would allow. Live submits also count against the daily (25 per rolling 24 h), per-platform (10) and per-run (10) limits; a user config can lower or raise them.

Safety model

1. Dry-run by default. dry_run = true unless you change it; init always writes it.
2. Approval tokens. plan_application returns a token bound to a hash of the exact answers. A real submit needs that token, so what you reviewed is what is sent (apply.auto_approve turns this off; do not).
3. Control layer. Independent checks run before every side effect: daily and per-run quotas, single-submit guard, recipient deny-list, prose lint, page-text injection screen, apply_enabled kill switch. Add your own rules in controls.toml.
4. Hard stops. Visible CAPTCHA challenges and attestation checkboxes matching policy.stop_phrases (for example "no AI used") always return needs_human. They are not configurable away. Verification codes are entered only when the USER types them, confirms a granted prefill (ADR-0026/0027), or consented to unattended runs from a terminal (item 8). Account creation is off by default; it needs accounts.auto_create = true in your own user config file AND an open credentials consent window (ADR-0046).
5. No invented facts. Answers come from your profile or are marked; unresolved required fields stop the run. Autonomy level (ADR-0052). [answers] autonomy in your own user config decides what the agent may assume when you are not available: strict (default: every unresolved field waits for you), safe_default (decline contact/marketing permission, the configured "how did you hear" default, "decline to self-identify"), or infer (also skill/experience questions about a tool or technology, answered from your resume: Yes only when it clearly says so, otherwise No; willingness, availability, location and terms questions are never inferred). Authorization/visa/identity, background and other screening, accommodation, recording, attestations, legal agreements and employment terms, salary without a policy, start date and location facts are never assumed. Every assumed answer is labelled (assumed, plan, evidence, run report); after promote_after (3) assumptions of one question you are asked once and your answer is reused. A project file or env var can only make the level stricter. init asks which level to use; control_status shows it.
6. Privacy. Profile and secrets stay on your machine, are never committed, and API keys are read only from the environment. See SECURITY.md.
7. Credentials never reach the model. ATS logins live in the OS keychain (job-apply-mcp vault add <host> --username U, password prompted without echo). The browser fills them straight into the page; MCP exposes only vault_status (hosts, never secrets). At most 2 sign-in attempts per host per run; a lockout or wrong password stops that host (ADR-0046).
8. Consent window (optional, ADR-0048). job-apply-mcp consent --for 24h (or --per-run, --max N, --scopes ...) is typed once, in a terminal, per period you choose. Inside the window submissions are approved automatically (logged with the consent id), a page whose only bot check is an invisible widget is submitted with one click, and an emailed code is read from the newest message of the expected sender and entered once. Unattended codes stay off until verification.trusted_authserv_ids lists your own mail server's Authentication-Results id (user config only), so a spoofed sender cannot supply a code. You review the results afterwards (list_applications). consent --revoke ends it; consent_status (MCP) is read-only and no tool can create one.
9. Owner-only questions (ADR-0050). Contact, messaging and marketing permissions (SMS, WhatsApp, calls, email, job alerts, talent community) are never answered Yes; only your own optin:<channel> answer applies, and only to a single, plain permission question. Otherwise they stay with you, or are declined (labelled assumed) at answers.autonomy = "safe_default" or "infer" (item 5). Authorization and sponsorship come only from structured per-country facts.

Transports

job-apply-mcp                                                  # stdio (what clients launch)
job-apply-mcp --transport http --host 127.0.0.1 --port 8765   # http://127.0.0.1:8765/mcp
JOB_APPLY_MCP_TOKEN=... job-apply-mcp --transport http --host 0.0.0.0   # non-local: token required

HTTP binds loopback by default; any other address refuses to start without JOB_APPLY_MCP_TOKEN (Authorization: Bearer ...). Use a TLS reverse proxy for network access. A Dockerfile is included (no browser by default; --build-arg BROWSER=1 adds Playwright and Chromium).

Documentation

• Client setup guides: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Codex CLI, Gemini CLI, Continue, generic JSON
• Tool reference and configuration reference (generated)
• FAQ, CHANGELOG, design decisions, CONTRIBUTING

Development

git clone https://github.com/tanmayagrawal21/job-apply-mcp && cd job-apply-mcp
uv sync --extra dev
uv run ruff check . && uv run pytest -q      # offline; live tests need JAM_LIVE=1
uv run python scripts/gen_config_docs.py     # after changing config.py

Privacy scan: python scripts/privacy_scan.py --terms ~/.config/job-apply-mcp/privacy_terms.txt. Owner-accepted findings go in ~/.config/job-apply-mcp/privacy_allow.txt (outside the repo, --allow FILE); see ADR-0051. The committed .privacy-allow holds only fully anchored regexes for fictional fixtures and the public project identity in manifests (ADR-0042); never add private terms or fingerprints to it.

MIT licensed. Contributions welcome under the Code of Conduct.