job104-mcp

An MCP server for searching 104 人力銀行 job listings with natural-language filters. Works with any MCP client — Claude, Cursor, Windsurf, Cline, Zed, VS Code, and others.

Disclaimer: This is an unofficial, educational/personal-use tool. It is not affiliated with, endorsed by, or sponsored by 104 Corporation. It calls 104's public web endpoints; please respect 104's Terms of Service and use it at a reasonable, low frequency. No scraped job data is distributed with this project.

How it works

104 sits behind Cloudflare bot protection — a plain HTTP request to its JSON API returns 403. This server uses curl_cffi with impersonate="chrome" to match a real browser's TLS fingerprint, so the same public endpoints return their normal JSON. The AI sees clean structured results; the 104 category/area codes are resolved from Chinese names automatically.

Prerequisite: install uv

Every install path runs the server through uv, so it must be installed first (uvx ships with uv):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Install in any MCP client (Cursor, Windsurf, Cline, Zed, VS Code, …)

MCP is an open protocol, so any MCP-capable client works — not just Claude. Add this to the client's MCP config (e.g. Cursor's ~/.cursor/mcp.json); the command/args form is what most clients accept:

{
  "mcpServers": {
    "job104": { "command": "uvx", "args": ["job104-mcp@latest"] }
  }
}

Install in Claude Code (User scope)

claude mcp add job104 -s user -- uvx job104-mcp@latest

Or from a local clone (no PyPI required):

claude mcp add job104 -- uv run --project /absolute/path/to/job104-mcp -m job104_mcp

Install in Claude Desktop (.mcpb bundle)

The .mcpb bundle is a Claude-Desktop-only convenience (other clients use the JSON config above). Download job104-mcp-vX.Y.Z.mcpb from the Releases page and double-click it (or drag it into Claude Desktop → Settings → Extensions).

To build the bundle yourself:

npx @anthropic-ai/mcpb pack .   # produces job104-mcp.mcpb

Run manually (stdio)

uv run job104-mcp
# or
uv run python -m job104_mcp

Tools

• search_jobs — search with keyword, area, job category, salary floor, remote, recency, experience, education, sort, paging. Use Chinese names for area/jobcat (e.g. ["台北市大安區"], ["軟體工程師"]); they resolve to 104 codes automatically. Each result carries a detail_id.
• get_job_detail — full posting for a detail_id from search_jobs.
• lookup_code — resolve a job-category or area name to its 104 code.

Refresh code tables

The bundled jobcat.json / area.json come from 104's public category tool. Regenerate:

uv run python scripts/fetch_codes.py

Tests

uv run pytest            # fast unit tests
uv run pytest -m live    # hits the real 104 site

Releasing (maintainer)

Releases are automated by .github/workflows/release.yml, triggered when the version in pyproject.toml changes on main. It publishes to PyPI, builds the .mcpb bundle, and attaches it to a GitHub Release.

One-time PyPI setup (uses Trusted Publishing, no API token stored): on https://pypi.org/manage/account/publishing/ add a pending publisher with project job104-mcp, owner mozzan, repo job104-mcp, workflow release.yml.

To cut a release: bump version in pyproject.toml, commit to main.

License

MIT — see LICENSE. Provided as-is, without warranty.