job104-mcp

An MCP server for searching 104 人力銀行 job listings with natural-language filters, for use with Claude Desktop, Cursor, and other MCP clients.

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.

Related MCP server: JobDataLake MCP Server

Install in Claude Code

Once published to PyPI, no manual install is needed — uvx fetches it on demand:

claude mcp add job104 -- 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)

Download job104-mcp-vX.Y.Z.mcpb from the Releases page and double-click it (or drag it into Claude Desktop → Settings → Extensions). Claude Desktop runs it via uv, so uv must be installed.

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.