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

Related MCP server: LinkedIn Agent MCP

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

🚀 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.

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://..."
  }
}

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.