handshake-mcp-server 0.1.0

MCP server for scraping Handshake (joinhandshake.com) — student profiles, employers, jobs, and events

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

Tool	Description	Status
get_student_profile	Get a student's profile by user ID (education, experience, skills, etc.)	Working
get_employer_profile	Get employer overview, open jobs, and reviews	Working
search_employers	Search for employers by keyword	Working
get_job_details	Get full job/internship posting with metadata (salary, visa, dates)	Working
search_jobs	Search jobs with keyword, location, type, and sort filters	Working
get_event_details	Get event details for career fairs and info sessions	Working
search_events	Search for upcoming events	Working
close_session	Close the browser session and free resources	Working

[!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

🔧 CLI Options

Flag	Description
--login	Open browser for manual login, save profile, then exit
--logout	Clear saved authentication profile and exit
--status	Check current session status and exit
--no-headless	Run browser in headed (visible) mode
--virtual-display	Run via Xvfb virtual framebuffer (Linux only)
--vnc-login	Start a noVNC web server for browser-based login
--vnc-port	Port for noVNC server (default: 6080)
--transport	MCP transport: stdio (default) or streamable-http
--host	HTTP host (default: 127.0.0.1)
--port	HTTP port (default: 8000)
--log-level	DEBUG, INFO, WARNING, or ERROR (default: WARNING)

HTTP mode example:

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

❗ Troubleshooting

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

🔧 Useful Commands

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

❗ Troubleshooting

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

🔧 Development Commands

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"]
    }
  }
}

❗ Troubleshooting

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.

Environment	Solution
Desktop with GUI (macOS, Windows, Linux)	Use --no-headless — opens a real browser window
Headless Linux server	Use --virtual-display — Chrome runs non-headless against an Xvfb virtual display
Docker	Default CMD already uses --virtual-display

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.