Handshake Server

Through this Handshake MCP server, AI assistants like Claude can connect to your Handshake account — the leading job and internship platform for students. Search jobs, browse employers, explore events, and pull student or employer profiles, all from your AI chat.

Installation Methods

uvx Docker Development

Usage Examples

Find software engineering internships at companies in San Francisco

What events are coming up on Handshake this week?

Get details for job posting 12345678 — does it sponsor visas?

Show me the employer profile for Google on Handshake

Features & Tools

[!IMPORTANT] Handshake is a student-gated platform — you must have a valid student account and log in before tools will work. Run uvx handshake-mcp-server --login (or the setup wizard) to authenticate.

🚀 uvx Setup (Recommended)

Prerequisites: Install uv and a Handshake student account.

1. Install the Patchright Chromium browser (one-time)

uvx --from handshake-mcp-server patchright install chromium

2. Run the setup wizard

uvx handshake-mcp-server setup

The wizard asks whether you want Docker or local mode, handles login, and prints the exact claude mcp add-json command to register the server with your MCP client.

3. Register with your MCP client

After setup, paste the command the wizard printed. For example:

# Local mode (opens a browser window on your machine)
claude mcp add-json handshake '{"command":"uvx","args":["handshake-mcp-server"]}'

# Docker mode (runs headless in a container)
claude mcp add-json handshake '{"command":"uvx","args":["handshake-mcp-server","docker"]}'

Or add manually to your MCP client config (claude_desktop_config.json or equivalent):

{
  "mcpServers": {
    "handshake": {
      "command": "uvx",
      "args": ["handshake-mcp-server"]
    }
  }
}

Restart your MCP client. Done.

[!NOTE] The server keeps a single Chromium browser open for its entire lifetime — this avoids re-authentication overhead and makes subsequent tool calls much faster. With --no-headless, a browser window stays visible for the duration of the session. This is normal.

uvx Setup Help

uvx handshake-mcp-server --transport streamable-http --host 127.0.0.1 --port 8000

🐳 Docker Setup

Prerequisites: Docker installed and running. No other dependencies needed.

Docker runs the server headless inside a container using an Xvfb virtual display — no browser window on your machine. The browser profile (cookies/session) is stored in a named Docker volume (handshake-profile) and persists across container restarts.

1. One-time login

docker compose build
docker compose run --rm -p 6080:6080 handshake-mcp --vnc-login

Open http://localhost:6080/vnc.html in your browser and log into Handshake manually.

2. Start the server

docker compose up -d

The MCP server is now available at http://127.0.0.1:8000/mcp (streamable-http transport).

3. Configure your MCP client

{
  "mcpServers": {
    "handshake": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "handshake-profile:/home/pwuser/.handshake-mcp",
        "handshake-mcp-server",
        "--transport", "stdio",
        "--virtual-display"
      ]
    }
  }
}

Docker Setup Help

docker compose logs -f                                               # tail server logs
docker compose run --rm handshake-mcp --status                       # check session validity
docker compose down                                                  # stop the server
docker rmi -f handshake-mcp-server && docker volume rm -f handshake-profile  # full reset

🐍 Local Setup (Develop & Contribute)

Contributions are welcome! See CONTRIBUTING.md for architecture guidelines and the PR checklist. Please open an issue first to discuss your change before submitting a PR.

Prerequisites: Git and uv installed.

# 1. Clone the repository
git clone https://github.com/sudhxnva/handshake-mcp-server
cd handshake-mcp-server

# 2. Install dependencies
uv sync --group dev

# 3. Install the Chromium browser
uv run patchright install chromium

# 4. Log in (opens a browser window)
uv run -m handshake_mcp_server --login --no-headless

# 5. Start the server
uv run -m handshake_mcp_server --no-headless

Local Setup Help

uv run ruff check .          # lint
uv run ruff check . --fix    # lint + auto-fix
uv run ruff format .         # format
uv run ty check              # type check
uv run pytest                # tests
uv run pytest --cov          # tests with coverage

{
  "mcpServers": {
    "handshake": {
      "command": "uv",
      "args": ["--directory", "/path/to/handshake-mcp-server", "run", "-m", "handshake_mcp_server"]
    }
  }
}

Cloudflare Bot Detection

Patchright does not bypass Cloudflare's headless fingerprint when headless=True — that mode uses the chromium-headless-shell binary, which is trivially detected.

Cloudflare challenge pages are detected automatically and raise a RateLimitError if unresolved.

Tool Return Format

All scraping tools return:

{
  "url": "string",
  "sections": { "section_name": "raw text content" },
  "references": { "section_name": [{ "kind": "job", "url": "/jobs/123", "text": "..." }] },
  "section_errors": { "section_name": { "error_type": "...", "error_message": "..." } },
  "unknown_sections": ["invalid_section_name"]
}

get_job_details also returns a metadata key with structured fields:

{
  "metadata": {
    "id": "123", "title": "Software Engineer Intern", "company": "Acme Corp",
    "salary": 3000, "salary_type": "hourly",
    "work_type": "hybrid", "locations": ["San Francisco, CA"],
    "job_type": "internship", "employment_type": "part_time",
    "start_date": "2025-06-01", "end_date": "2025-08-31",
    "deadline": "2025-03-01", "posted_at": "2025-01-15",
    "work_auth_required": false, "accepts_opt": true, "accepts_cpt": false,
    "will_sponsor": true, "apply_url": "https://..."
  }
}

[!NOTE] Salary values from the GraphQL API are in cents — divide by 100 to get dollars.

search_jobs also returns jobs (card-level metadata list) and job_ids. search_employers returns employer_ids. search_events returns event_ids.

Acknowledgements

Built with FastMCP and Patchright. Inspired by the architecture of linkedin-mcp-server.

Use in accordance with Handshake's Terms of Service. Web scraping may violate platform terms. This tool is intended for personal use only.

License

Apache-2.0 — see LICENSE.