Handshake MCP 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

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

HTTP mode example:

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

Login issues:

• Make sure you have a valid Handshake student account
• Handshake may show a CAPTCHA on first login — --login opens a browser so you can solve it manually
• If your session expires, re-run uvx handshake-mcp-server --login

Cloudflare detection:

• Handshake uses Cloudflare bot protection. On any desktop with a GUI, always use --no-headless (the setup wizard does this automatically)
• On headless Linux servers, use --virtual-display to avoid the headless fingerprint
• See Cloudflare Bot Detection for details

Session issues:

• Browser profile is stored at ~/.handshake-mcp/profile/
• Run uvx handshake-mcp-server --status to check if your session is still valid
• Run uvx handshake-mcp-server --logout to clear the profile and start fresh

Installation issues:

• Ensure uv is installed: curl -LsSf https://astral.sh/uv/install.sh | sh
• Install the Chromium browser: uvx handshake-mcp-server will install it automatically on first run

🐳 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

Login issues:

• Open http://localhost:6080/vnc.html within 5 minutes of starting --vnc-login
• If the session expires, repeat the one-time login step
• Chromium may leave lock files (SingletonLock) in the profile dir after a container kill — the server cleans these up automatically on next start

Docker issues:

• Check Docker is running: docker ps
• Rebuild after pulling new code: docker compose build
• Full reset: docker rmi -f handshake-mcp-server && docker volume rm -f handshake-profile

🐍 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

Claude Desktop config for local dev:

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

Scraping issues:

• Use --no-headless to watch browser actions and debug scraping problems
• Add --log-level DEBUG for verbose logging

Python/Patchright issues:

• Requires Python 3.12+: python --version
• Reinstall Patchright: uv run patchright install chromium
• Reinstall dependencies: uv sync --reinstall

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.