yeswehack-mcp

yeswehack-mcp

A Model Context Protocol (MCP) server for the YesWeHack bug bounty platform. Lets Claude query your private and public programs, reports, and the hacktivity feed directly from a conversation.

Features

• Flexible authentication — browser login, email/password API login, copied bearer tokens, and official Personal Access Tokens.
• Private programs — returns invite-only programs you have been accepted into, not just public ones.
• Full program details — scope, reward ranges, status.
• Report access — list and read reports with severity, CVSS, description, and bounty.
• Report comments — list report discussion/messages when your account has access.
• Email aliases — list your YesWeHack email aliases.
• Program credentials — list credential pools/assigned credentials and request credentials for programs that expose pools.
• Hacktivity feed — browse publicly disclosed reports.
• Token caching — the JWT is stored locally and reused until it expires.

Requirements

• Python 3.10+
• uv (installed automatically by the setup script if missing)
• A YesWeHack account
• WSL2 users: WSLg must be enabled so Chromium can open a window (echo $DISPLAY should return a value)

Installation

git clone https://github.com/youruser/yeswehack-mcp
cd yeswehack-mcp

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Download the Chromium browser used for login
uv run playwright install chromium

Registering with Claude Code

claude mcp add yeswehack -- uv --directory /path/to/yeswehack-mcp run server.py

Replace /path/to/yeswehack-mcp with the actual path where you cloned the repo.

Verify it connected:

claude mcp list
# yeswehack: ... ✓ Connected

Registering with Claude Desktop

Add the following to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "yeswehack": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/yeswehack-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

If uv is not on PATH when Claude Desktop launches, use the absolute path (e.g. /home/youruser/.local/bin/uv).

Usage

Once registered, start every session by authenticating:

You: Call the authenticate tool

With no arguments, a Chromium window opens. Log in to YesWeHack as normal (email + password + 2FA if enabled). The window closes automatically once your session is detected. The token is saved to ~/.config/yeswehack-mcp/token.json and reused for all subsequent calls until it expires.

You can also authenticate without a browser:

authenticate(email="you@example.com", password="...", totp="123456")
authenticate(access_token="eyJ...")        # browser/API bearer token
authenticate(access_token="ywh_pat_...")   # Personal Access Token

Environment variables are supported too:

export YWH_TOKEN="eyJ..."       # browser/API bearer token
export YWH_PAT="ywh_pat_..."    # Personal Access Token

Available tools

| Tool | Description | |------|-------------| | authenticate | Browser login, API login, or store a copied bearer token/PAT | | get_current_user | Show your YesWeHack profile (username, rank, reputation) | | list_programs | List all programs you have access to, including private invite-only ones | | get_program | Full details for a program: scope, reward ranges, status | | list_reports | List reports for a program, with optional status filter | | get_report | Full details of a specific report (title, severity, CVSS, description, bounty) | | list_report_comments | List comments/messages for a report when your token has access | | list_email_aliases | List your YesWeHack email aliases | | get_program_credentials | List credential pools and assigned credentials for a program | | request_program_credentials | Request credentials from a program credential pool | | yeswehack_api_get | Read-only escape hatch for authenticated API endpoints not wrapped yet | | get_hacktivity | Browse the public hacktivity (disclosed reports) feed |

Example prompts

List all my private programs on YesWeHack.

Show me the scope for the program with slug "acme-corp".

List my YesWeHack email aliases.

Get credentials for program "acme-corp".

List all accepted reports for program "acme-corp".

Get the full details of report 12345.

Show me the latest hacktivity, page 2.

Token storage

The token is saved to ~/.config/yeswehack-mcp/token.json. It contains only the token and its expiry timestamp — no account password is ever stored. Browser/API session JWTs use their embedded expiry. Opaque Personal Access Tokens are cached locally until the YesWeHack API rejects them. The browser profile (cookies, localStorage) is kept at ~/.config/yeswehack-mcp/browser-profile so you do not have to fill in your email every time you re-authenticate.

To log out, delete the token file:

rm ~/.config/yeswehack-mcp/token.json

Project structure

yeswehack-mcp/
├── server.py        # FastMCP entry point — all tool definitions
├── auth.py          # Playwright browser login + token storage
├── client.py        # httpx async API wrapper with pagination
└── pyproject.toml   # Dependencies and build config

WSL2 display setup

Playwright needs a display to open the browser window. On WSL2 with WSLg this works out of the box. If you see an error about DISPLAY not being set:

# Check if WSLg is running
echo $DISPLAY        # should print something like :0
ls /mnt/wslg        # should exist

# If not, ensure you are on a recent WSL2 version with WSLg support
wsl --update         # run from Windows PowerShell

License

MIT