A Model Context Protocol (MCP) server that provides seamless integration with HackerOne's bug bounty platform through Claude Desktop. This server enables security professionals to efficiently manage vulnerability reports, perform triage operations, and maintain compliance with security directives directly from Claude.
- Comprehensive Report Management: Fetch and analyze new reports, all reports, or specific reports by ID
- Smart Duplicate Detection: Advanced similarity analysis to identify potential duplicate reports
- Scope Validation: Automated checking of reports against program scope and policies
- Weekly Reporting: Generate detailed weekly status reports with metrics and insights
- MDC Compliance: Built-in security directives and compliance checking for consistent operations
- Zero-Knowledge Architecture Support: Specialized handling for privacy-first security models
- Python 3.8 or higher
- Poetry (for dependency management)
- HackerOne API credentials
- Claude Desktop application
- Python: 3.8 or higher (3.9+ recommended)
- Operating System: macOS, Windows, or Linux
- Memory: 512MB RAM minimum for basic operation
- Network: Internet connection for HackerOne API access
git clone <repository-url>
cd hackerone-mcpPoetry provides better dependency management and virtual environment isolation.
# Install Poetry if you don't have it
curl -sSL https://install.python-poetry.org | python3 -
# Verify Poetry installation
poetry --version
# Install project dependencies
poetry install
# Verify installation
poetry run python --versionPoetry Troubleshooting:
- Mac/Linux: If
poetrycommand not found, add~/.local/binto your PATH - Windows: Poetry might install to
%APPDATA%\Python\Scripts- add to PATH - Permission Issues: Use
python3 -m pip install --user poetryas alternative
# Create virtual environment
python3 -m venv hackerone-mcp-env
# Activate virtual environment
# On macOS/Linux:
source hackerone-mcp-env/bin/activate
# On Windows:
hackerone-mcp-env\Scripts\activate
# Upgrade pip
pip install --upgrade pip
# Install dependencies
pip install httpx python-dotenv pyyaml mcp
# Verify installation
python --version
pip listThe server requires these packages (automatically installed by Poetry/pip):
- httpx (>=0.24.0) - HTTP client for HackerOne API
- python-dotenv (>=0.19.0) - Environment variable loading
- pyyaml (>=6.0) - YAML parsing for MDC files
- mcp (>=0.1.0) - Model Context Protocol server framework
1. Python Version Issues:
# Check Python version
python --version
python3 --version
# If Python < 3.8, install newer version:
# macOS: brew install python@3.11
# Ubuntu: sudo apt install python3.11
# Windows: Download from python.org2. SSL Certificate Errors:
# macOS SSL issues
/Applications/Python\ 3.x/Install\ Certificates.command
# Or upgrade certificates
pip install --upgrade certifi3. Compilation Errors (especially on older systems):
# Install development tools
# Ubuntu/Debian:
sudo apt-get install build-essential python3-dev
# CentOS/RHEL:
sudo yum groupinstall "Development Tools"
sudo yum install python3-devel
# macOS: Install Xcode command line tools
xcode-select --installCreate a .env file in the project root directory:
# Navigate to project root
cd hackerone-mcp
# Create .env file
touch .env
# Edit with your preferred editor
nano .env
# or
code .envAdd the following content:
# HackerOne API credentials
H1_USERNAME=your_hackerone_username
H1_API_TOKEN=your_hackerone_api_token
H1_PROGRAM=your_program_handle
# Optional: Custom MDC file path
# MDC_FILE_PATH=/custom/path/to/your/mdc/file.mdcGetting HackerOne API Credentials:
- Log into HackerOne: Go to hackerone.com and sign in
- Navigate to Settings: Click your profile → Settings
- API Tokens Section: Go to "API Tokens" tab
- Create Token: Click "Create API Token"
- Copy Credentials:
- Username: Your HackerOne username (not email)
- API Token: The generated token (starts with
h1_)
- Find Program Handle: Your program handle is in the URL:
https://hackerone.com/your_program_handle
- No Quotes: Don't wrap values in quotes in .env file
- No Spaces:
H1_USERNAME=valuenotH1_USERNAME = value - File Location:
.envmust be in the project root directory - Git Ignore: Never commit
.envto version control (already in .gitignore)
Instead of .env file, you can set system environment variables:
# macOS/Linux (add to ~/.bashrc or ~/.zshrc)
export H1_USERNAME="your_username"
export H1_API_TOKEN="your_token"
export H1_PROGRAM="your_program"
# Windows (Command Prompt)
setx H1_USERNAME "your_username"
setx H1_API_TOKEN "your_token"
setx H1_PROGRAM "your_program"
# Windows (PowerShell)
$env:H1_USERNAME="your_username"
$env:H1_API_TOKEN="your_token"
$env:H1_PROGRAM="your_program"The server includes security compliance directives through a Management Directive Compliance (MDC) file.
- Locate MDC File: The placeholder is at
rules/hackerone_mcp_directives.mdc ⚠️ CRITICAL: Update the hardcoded path insrc/hackerone_mcp/main.py:
The MDC file path is now automatically configured to use dynamic paths relative to the project root. The current implementation:
# Dynamic MDC file path - relative to project root
def get_project_root() -> Path:
"""Get the project root directory"""
return Path(__file__).parent.parent.parent
# MDC file path - can be overridden with environment variable
MDC_FILE_PATH = os.getenv("MDC_FILE_PATH", str(get_project_root() / "rules" / "hackerone_mcp_directives.mdc"))This automatically finds the project root and locates the MDC file, while still allowing customization via the MDC_FILE_PATH environment variable.
- Verify MDC File Exists:
# Check if MDC file exists
ls -la rules/hackerone_mcp_directives.mdc
# If missing, create placeholder
mkdir -p rules
touch rules/hackerone_mcp_directives.mdc# Using Poetry
poetry run python src/hackerone_mcp/main.py --help
# Using pip/venv
python src/hackerone_mcp/main.py --helpCreate a test script test_setup.py:
import os
from dotenv import load_dotenv
import httpx
import yaml
# Test environment loading
load_dotenv()
print("✓ Environment variables loaded")
# Test credentials
username = os.getenv("H1_USERNAME")
token = os.getenv("H1_API_TOKEN")
program = os.getenv("H1_PROGRAM")
if not all([username, token, program]):
print("❌ Missing credentials")
exit(1)
print("✓ Credentials configured")
# Test network connectivity
try:
response = httpx.get("https://api.hackerone.com/v1/me", timeout=10)
print("✓ HackerOne API accessible")
except Exception as e:
print(f"❌ Network issue: {e}")
print("✅ Setup verification complete!")Run the test:
# Using Poetry
poetry run python test_setup.py
# Using pip/venv
python test_setup.pyError: MDC file not found at /path/to/rules/hackerone_mcp_directives.mdc
Solution:
- Ensure the MDC file exists:
ls -la rules/hackerone_mcp_directives.mdc - Create the directory if missing:
mkdir -p rules - Or set custom path via environment:
export MDC_FILE_PATH="/your/custom/path/file.mdc"
ModuleNotFoundError: No module named 'httpx'
Solution:
- Ensure virtual environment is activated
- Reinstall dependencies:
poetry installorpip install -r requirements.txt
PermissionError: [Errno 13] Permission denied
Solution:
- Check file permissions:
chmod +x src/hackerone_mcp/main.py - Don't run with
sudo- use virtual environments instead
python: command not found
Solution:
- Use
python3instead ofpython - Check Python installation:
which python3 - Add Python to PATH (Windows)
poetry: command not found
Solution:
- Add Poetry to PATH:
export PATH="$HOME/.local/bin:$PATH" - Or install via pip:
pip install poetry - Restart terminal after installation
SSL: CERTIFICATE_VERIFY_FAILED
Solution:
- Update certificates:
pip install --upgrade certifi - macOS: Run
/Applications/Python\ 3.x/Install\ Certificates.command
Error: HackerOne API returned status 401
Solution:
- Verify credentials are correct
- Check if API token has proper permissions
- Ensure program handle is exact (case-sensitive)
Test that the dynamic path system is working correctly:
# Run the path test script
python test_paths.py
# Expected output:
🔍 Path Resolution Test
==================================================
Current working directory: /path/to/hackerone-mcp
Test script location: /path/to/hackerone-mcp
Detected project root: /path/to/hackerone-mcp
MDC file path: /path/to/hackerone-mcp/rules/hackerone_mcp_directives.mdc
✅ MDC file found at: /path/to/hackerone-mcp/rules/hackerone_mcp_directives.mdc
🔧 Environment Variable Test
==================================================
Custom MDC path: /tmp/test_mdc.mdc
✅ Path resolution test completed successfully!If everything is working correctly, you should see:
# Run the server directly
poetry run python src/hackerone_mcp/main.py
# Expected output:
HackerOne MCP Server with MDC starting...
Server name: hackerone-mcp
Program: your_program_handle
Credentials configured: True
MDC directives loaded: True
Server running, waiting for messages...Press Ctrl+C to stop the test.
Find your Claude Desktop configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
Linux:
~/.config/Claude/claude_desktop_config.json
Add the HackerOne MCP server to your Claude Desktop configuration:
{
"mcpServers": {
"hackerone-mcp": {
"command": "python",
"args": ["/absolute/path/to/hackerone-mcp/src/hackerone_mcp/main.py"],
"env": {
"H1_USERNAME": "your_hackerone_username",
"H1_API_TOKEN": "your_hackerone_api_token",
"H1_PROGRAM": "your_program_handle"
}
}
}
}Important: Replace /absolute/path/to/hackerone-mcp with the full path to your project directory.
If using Poetry, use this configuration instead:
{
"mcpServers": {
"hackerone-mcp": {
"command": "poetry",
"args": ["run", "python", "src/hackerone_mcp/main.py"],
"cwd": "/absolute/path/to/hackerone-mcp",
"env": {
"H1_USERNAME": "your_hackerone_username",
"H1_API_TOKEN": "your_hackerone_api_token",
"H1_PROGRAM": "your_program_handle"
}
}
}
}Close and restart Claude Desktop to load the new MCP server configuration.
In Claude Desktop, you should see the HackerOne MCP server listed in your available tools. You can test it by asking:
"Show me new HackerOne reports"
Once connected, you can interact with your HackerOne program directly through Claude Desktop using natural language. The server provides 6 powerful tools that integrate seamlessly into your security workflow.
After connecting the server, Claude Desktop will automatically have access to your HackerOne tools. You can:
- Ask questions in natural language - Claude will determine which tools to use
- Request specific actions - Directly ask for reports, analysis, or checks
- Get guided assistance - The MDC directives will provide security guidance automatically
Here are practical examples of how to interact with the server:
You: "What new vulnerability reports do I have?"
Claude will: Use get_new_reports to fetch all reports in "new" state, format them with complete details, and provide MDC triage guidance including initial questions to ask and escalation checks.
You: "Show me all reports for my program"
Claude will: Use get_all_reports to fetch comprehensive data on all reports regardless of state, with full metrics and status information.
You: "Can you analyze report #1234567 for me?"
Claude will: Use check_report to get complete details including vulnerability information, timeline, reporter stats, severity assessment, and provide MDC-guided security recommendations.
You: "I need the full technical details for report 1234567"
Claude will: Fetch the complete report with both formatted summary and raw JSON data, plus security guidance on next steps.
You: "Is report #1234567 within our program scope?"
Claude will: Use check_scope to compare the report against your program's structured scope, policy rules, bounty eligibility, and provide detailed scope analysis with recommendations.
You: "Check if report #1234567 is a duplicate"
Claude will: Use check_duplicate to perform intelligent similarity analysis across all program reports, scoring potential duplicates based on titles, weaknesses, assets, and vulnerability descriptions.
You: "Generate this week's security report"
Claude will: Use make_weekly_report to create comprehensive weekly analysis including compliance checks, metrics, trends, closed reports analysis, and actionable insights for management.
You: "What's our program's current status and any urgent items?"
Claude will: Generate weekly report focusing on immediate attention items, compliance-critical vulnerabilities, and recent activity requiring follow-up.
"Show me new reports that need triage"
"What new vulnerabilities came in today?"
"Are there any new reports requiring immediate escalation?"
What you get:
- Complete new reports with vulnerability details
- MDC triage questions automatically provided
- Escalation alerts for critical issues
- Researcher interaction guidelines
- Security compliance reminders
"Give me a complete overview of all reports"
"Show me the current state of all vulnerabilities"
"What's the full picture of our bug bounty program?"
What you get:
- Comprehensive report listing across all states
- Program performance metrics
- State distribution analysis
- Complete vulnerability timeline data
"Tell me everything about report #1234567"
"I need full analysis of report 1234567"
"Show me the technical details for this specific report"
What you get:
- Complete vulnerability information and timeline
- Reporter statistics and history
- Severity assessment and methodology
- Raw JSON data for advanced analysis
- MDC security guidance and next steps
"Is report #1234567 in scope?"
"Check if this vulnerability affects our covered assets"
"Validate the scope for report 1234567"
What you get:
- Detailed scope analysis against program policy
- Asset matching and bounty eligibility
- Maximum severity limits for the asset
- Comprehensive policy comparison
- MDC scope validation checklist
"Is report #1234567 a duplicate?"
"Check for similar reports to #1234567"
"Analyze potential duplicates for this report"
What you get:
- Similarity scoring across multiple criteria
- Categorized potential duplicates (likely/possible)
- Detailed comparison reasoning
- Historical report correlation
- MDC duplicate determination guidelines
"Create this week's status report"
"What's our weekly security summary?"
"Generate management report for this week"
What you get:
- Comprehensive weekly activity analysis
- Compliance framework status updates
- Detailed closed reports outcomes
- Trending analysis and metrics
- Executive summary with actionable insights
- Zero-knowledge architecture integrity assessment
"Check report #1234567 for duplicates, scope, and give me full analysis"
Claude will automatically use multiple tools (check_duplicate, check_scope, check_report) to provide comprehensive analysis.
You: "Show me new reports"
Claude: [Shows 5 new reports]
You: "Check if the first one is a duplicate"
Claude remembers context and will check the first report from the previous response.
"What reports this week need immediate security attention?"
"Are there any compliance-critical vulnerabilities I should know about?"
"Show me zero-knowledge architecture related reports"
The MDC framework automatically provides security-focused analysis and recommendations.
Every tool response includes:
- 🔒 Security Guidance - Automatic policy compliance checks
⚠️ Escalation Alerts - Immediate attention triggers- 📋 Triage Questions - Initial assessment prompts
- ✅ Validation Checklists - Required verification steps
- 💡 Best Practices - Researcher interaction guidelines
The server provides multiple data formats:
- 📝 Formatted Summaries - Human-readable analysis
- 📊 Structured Data - Organized metrics and timelines
- 🔍 Raw JSON - Complete API responses for advanced use
- 📈 Visual Analytics - Trend analysis and comparisons
- 🎯 Action Items - Specific next steps and recommendations
Fetches all new reports (state=new) for your program with comprehensive details including reporter info, severity, and vulnerability details.
Fetches all reports regardless of state for comprehensive program analysis.
Retrieves detailed information for a specific report by ID, including complete vulnerability information and timeline.
Usage: check_report(report_id="123456")
Analyzes whether a specific report falls within your program's scope by comparing against structured scope rules and policy.
Usage: check_scope(report_id="123456")
Performs intelligent duplicate analysis using similarity scoring across titles, weaknesses, assets, and vulnerability descriptions.
Usage: check_duplicate(report_id="123456")
Generates comprehensive weekly status reports with metrics, trends, compliance analysis, and actionable insights.
The Management Directive Compliance (MDC) file is a YAML configuration that defines your organization's security policies, triage workflows, and compliance requirements. This guide helps you customize the placeholder file for your specific needs.
The MDC file is organized into several key sections:
# Core organizational mission and principles
core_directives:
primary_mission: "Your organization's security mission statement"
# Operational decision-making framework
operational_principles:
decision_framework:
- "Evidence-based security decisions"
- "Risk-proportionate responses"
# HackerOne-specific security policies
hackerone_specific_rules:
report_triage:
classification_questions:
- "What is the actual security impact?"
- "Is this reproducible in production?"
researcher_interaction:
always:
- "Acknowledge receipt within 24 hours"
- "Provide clear next steps"
never:
- "Dismiss reports without investigation"
- "Use dismissive language"
# Compliance and validation workflows
validation_workflows:
before_report_closure:
ask:
- "Has impact been fully assessed?"
- "Are compliance requirements met?"
# Escalation triggers and procedures
escalation_triggers:
immediate_escalation:
- "zero-day"
- "data breach"
- "authentication bypass"
questions_during_escalation:
- "Who needs immediate notification?"
- "What compliance reporting is required?"
# Daily operational reminders
reminder:
core_philosophy: "Your key security principle or reminder"Replace the placeholder mission with your organization's actual security objectives:
core_directives:
primary_mission: "Protect customer data through proactive vulnerability management and rapid incident response"Customize questions based on your specific threat model and business context:
hackerone_specific_rules:
report_triage:
classification_questions:
- "Does this affect customer data?"
- "Is this exploitable in our production environment?"
- "What is the CVSS score based on our infrastructure?"
- "Are there compensating controls in place?"Define specific validation requirements for different severity levels:
hackerone_specific_rules:
report_triage:
severity_assessment:
critical:
ask_before_marking: "Has executive team been notified?"
verification: "Confirmed exploitable in production"
high:
clarify: "Business impact assessment completed"
medium:
verification: "Reproducibility confirmed"Define your organization's communication standards:
hackerone_specific_rules:
researcher_interaction:
always:
- "Respond within your published SLA timeframe"
- "Provide technical rationale for decisions"
- "Thank researchers for their contributions"
never:
- "Share internal vulnerability assessment details"
- "Make promises about fix timelines without approval"Set keywords and conditions that require immediate escalation:
escalation_triggers:
immediate_escalation:
- "remote code execution"
- "sql injection"
- "authentication bypass"
- "privilege escalation"
- "your-critical-system-name"
questions_during_escalation:
- "Has the security team lead been notified?"
- "Is this affecting production systems?"
- "Do we need to invoke incident response procedures?"Create checklists for different operational stages:
validation_workflows:
before_report_closure:
ask:
- "Has the fix been deployed and verified?"
- "Has the researcher been properly thanked?"
- "Are compliance documentation requirements met?"
before_bounty_award:
ask:
- "Is the bounty amount consistent with our policy?"
- "Has the impact been properly validated?"escalation_triggers:
immediate_escalation:
- "payment processing"
- "customer financial data"
- "regulatory compliance"
validation_workflows:
before_report_closure:
ask:
- "Does this require regulatory notification?"
- "Has PCI DSS impact been assessed?"escalation_triggers:
immediate_escalation:
- "patient data"
- "hipaa"
- "phi exposure"
validation_workflows:
before_report_closure:
ask:
- "Has HIPAA compliance officer been notified?"
- "Is patient data exposure documented?"escalation_triggers:
immediate_escalation:
- "customer data access"
- "multi-tenant isolation"
- "api authentication"
hackerone_specific_rules:
report_triage:
classification_questions:
- "Does this affect multiple customers?"
- "Can this be exploited at scale?"After customizing your MDC file:
- Validate YAML Syntax: Use a YAML validator to ensure proper formatting
- Test with Sample Reports: Run the server against test data to verify your rules work as expected
- Review with Security Team: Have your security team review the policies and escalation triggers
- Iterate Based on Usage: Adjust rules based on real-world usage and feedback
- Keep It Updated: Review and update your MDC file quarterly
- Version Control: Track changes to your MDC file in version control
- Document Changes: Maintain a changelog for MDC policy updates
- Team Training: Ensure your team understands the policies defined in the MDC
- Regular Audits: Periodically audit whether your actual practices match your MDC policies
The server includes built-in security compliance features:
- Triage Guidance: Automated prompts for essential security questions
- Escalation Detection: Automatic identification of reports requiring immediate attention
- Researcher Interaction Guidelines: Best practices for professional communication
- Compliance Checks: Built-in validation against security frameworks
1. "Credentials not configured" error
- Verify your
.envfile contains correct HackerOne credentials - Ensure environment variables are properly set in Claude Desktop configuration
2. "Program not found" error
- Check that your
H1_PROGRAMvalue matches your actual program handle - Verify you have access to the specified program in HackerOne
3. "Connection timeout" errors
- Check your internet connection
- Verify HackerOne API is accessible from your network
- Consider increasing timeout values if on a slow connection
4. Claude Desktop doesn't show the server
- Verify the absolute path in your configuration is correct
- Check that Python/Poetry is available in your system PATH
- Review Claude Desktop logs for error messages
To enable debug logging, run the server directly:
# Using Poetry
poetry run python src/hackerone_mcp/main.py
# Using Python directly
python src/hackerone_mcp/main.pyThis will show detailed logging information to help diagnose issues.
Claude Desktop logs can be found at:
- macOS:
~/Library/Logs/Claude/ - Windows:
%APPDATA%\Claude\logs\ - Linux:
~/.config/Claude/logs/
- Store API credentials securely and never commit them to version control
- Use environment variables or secure credential management systems
- Regularly rotate your HackerOne API tokens
- Monitor API usage to detect any unauthorized access
- Follow your organization's security policies for API integrations
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
For issues related to:
- HackerOne API: Check HackerOne's API documentation and support
- Claude Desktop: Refer to Anthropic's Claude Desktop documentation
- This MCP Server: Open an issue in this repository
- Initial release with core HackerOne integration
- MDC compliance framework integration
- Full report management capabilities
- Claude Desktop MCP integration