Handshake MCP Server

<p align="left"> <a href="https://pypi.org/project/handshake-mcp-server/" target="_blank"><img src="https://img.shields.io/pypi/v/handshake-mcp-server?color=blue" alt="PyPI"></a> <a href="https://github.com/sudhxnva/handshake-mcp-server/actions/workflows/ci.yml" target="_blank"><img src="https://github.com/sudhxnva/handshake-mcp-server/actions/workflows/ci.yml/badge.svg?branch=master" alt="CI Status"></a> <a href="https://github.com/sudhxnva/handshake-mcp-server/actions/workflows/publish.yml" target="_blank"><img src="https://github.com/sudhxnva/handshake-mcp-server/actions/workflows/publish.yml/badge.svg" alt="Publish"></a> <a href="https://github.com/sudhxnva/handshake-mcp-server/blob/master/LICENSE" target="_blank"><img src="https://img.shields.io/badge/License-Apache%202.0-brightgreen?labelColor=32383f" alt="License"></a> </p>

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

<!-- TODO: Add demo video here -->

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.

<br/>

🚀 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

<details> <summary><b>🔧 CLI Options</b></summary>

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

</details>

<details> <summary><b>❗ Troubleshooting</b></summary>

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

</details>

<br/>

🐳 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

<details> <summary><b>🔧 Useful Commands</b></summary>

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

</details>

<details> <summary><b>❗ Troubleshooting</b></summary>

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

</details>

<br/>

🐍 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

<details> <summary><b>🔧 Development Commands</b></summary>

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

</details>

<details> <summary><b>❗ Troubleshooting</b></summary>

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

</details>

<br/>

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.

<br/>

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.

<br/>

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.