employed-mcp

employed-mcp

An MCP server and CLI for Employed by Guaq AI - every role we've verified live on a real employer ATS, queryable by an LLM (MCP) or from a shell (CLI). Full API reference: https://jobs.guaqai.me/docs.

This package is a thin Node launcher, nothing more - full functionality, nothing held back for not being written in JavaScript. The actual client (guaq_client.py/guaq_cli.py/guaq_mcp.py) is the same code the API docs let you curl directly; every filter, subcommand and MCP tool it exposes works identically either way. npx employed-mcp / npx employed exist purely so you don't have to find and download those files yourself - under the hood they still just run Python. A Python 3.8+ interpreter on PATH (python3, or python/py on Windows) is required - this package cannot supply one, and that's the only thing "one-click" doesn't cover: if Python isn't already on the machine, that's a second install, not zero.

Get an API key

Sign in at https://jobs.guaqai.me/profile and generate a key (guaq_sk_...).

MCP server

# Try it directly - this is the whole install step
GUAQ_API_KEY=guaq_sk_... npx -y employed-mcp

# Claude Code: one command, user scope. Works in any folder, with no approval prompt.
claude mcp add --scope user employed --env GUAQ_API_KEY=guaq_sk_... -- npx -y employed-mcp

# Windows PowerShell: quote the "--" separator so PowerShell does not strip it:
claude mcp add --scope user employed --env GUAQ_API_KEY=guaq_sk_... "--" npx -y employed-mcp

Then start a new Claude Code session and run /mcp: employed should be listed as connected. Do not put the key in a project .mcp.json unless you explicitly want it per-repo. A project server is only loaded after you interactively approve it in that exact directory, and that approval prompt is easy to miss or suppress.

Troubleshooting

• employed is missing from /mcp: check claude mcp list. If it's absent, re-run the claude mcp add --scope user command above and restart the session.
• Project .mcp.json server shows as "needs approval" / pending: Project-scoped servers require interactive prompt confirmation when Claude Code launches in that specific directory. If Claude Code is launched from a parent/different directory or the prompt was dismissed, the server remains unapproved. Fix: remove the project entry (claude mcp remove employed) and add it at user scope (claude mcp add --scope user ...), or run claude mcp reset-project-choices and reopen the session from the folder with .mcp.json.
• Tools load but calls fail with 401: the key is wrong or revoked. Generate a new one at https://jobs.guaqai.me/profile and re-run claude mcp add --scope user (it replaces the entry).
• python3 not found: install Python 3.8+ (see "No Python found?" below).

Claude Desktop (claude_desktop_config.json - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "employed": {
      "command": "npx",
      "args": ["-y", "employed-mcp"],
      "env": { "GUAQ_API_KEY": "guaq_sk_..." }
    }
  }
}

Restart the host after editing its config.

CLI

export GUAQ_API_KEY=guaq_sk_...
npx -y employed-mcp jobs --domain tech --location-scope india --limit 10
npx -y employed-mcp count --company "Jane Street" --role-type new_grad
npx -y employed-mcp export jobs.parquet --format parquet --domain finance
npx -y employed-mcp signals india
npx -y employed-mcp company "Optiver"

Install it once instead of re-fetching every time with npm install -g employed-mcp, then just run employed-mcp (or employed) directly.

What this package actually ships

bin/mcp.js   bin/cli.js   bin/_run.js   - the Node launcher (finds python3, execs it)
py/guaq_client.py   py/guaq_cli.py   py/guaq_mcp.py   - synced from the canonical
                                                          source at publish time

The py/ files are regenerated from scraper/guaq_*.py in the resume-cv monorepo on every npm pack/ npm publish (see scripts/sync-python.js) - this package is never hand-edited to add functionality; edit the source there instead. See PUBLISHING.md for the release process.

No Python found?

Install Python 3.8+ from https://python.org and make sure python3 (or python on Windows) resolves on PATH, then try again. This package intentionally does not bundle or auto-install an interpreter.

Support

Email [e-mail], or raise a ticket from Profile → Support at https://jobs.guaqai.me once signed in.