GoPhish MCP Server

A Model Context Protocol (MCP) server for the GoPhish phishing simulation platform API.

STRICTLY READ-ONLY

This server is strictly read-only and only accepts GET requests. No modifications to campaigns, templates, groups, or any other GoPhish data can be made through this server.

Privacy Protection

All email addresses returned by this server are automatically masked for privacy protection using the format: j***n@e***.com (first character, masked middle, last character @ first character of domain, masked rest, TLD).

Features

• List and analyze phishing campaigns
• View campaign results and statistics
• Access campaign timelines
• List target groups (without exposing individual emails)
• View email templates
• List landing pages
• Calculate engagement rates (open, click, submit, report)

Prerequisites

1. GoPhish Instance: You need a running GoPhish server
2. API Key: Generate an API key from your GoPhish admin panel
3. HTTPS or Localhost: API URL must use HTTPS or be localhost for security

Installation

cd gophish
bun install

Configuration

Set the following environment variables:

export GOPHISH_API_URL="https://your-gophish-instance.com"
export GOPHISH_API_KEY="your-api-key-here"

Security Requirements

• GOPHISH_API_URL must use HTTPS protocol OR be localhost (127.0.0.1/::1)
• API key is passed in the Authorization header (GoPhish standard)
• Only GET requests are allowed (enforced in code)

Usage

Build and Run

# Build the server
bun run build

# Run the server
bun run start

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "gophish": {
      "command": "bun",
      "args": ["run", "/Users/ehenry/Documents/code/mcp-servers/gophish/src/index.ts"],
      "env": {
        "GOPHISH_API_URL": "https://your-gophish-instance.com",
        "GOPHISH_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

1. gophish_campaign_list

List all campaigns with summary statistics.

Parameters:

• limit (optional): Maximum number of results (1-100, default 25)

Returns:

• Campaign metadata (id, name, status, dates)
• Statistics (total, sent, opened, clicked, submitted, reported)

Example:

{
  "limit": 10
}

2. gophish_campaign_results

Get detailed results for a specific campaign with masked emails.

Parameters:

• campaign_id (required): Campaign ID (positive integer)

Returns:

• Individual target results with masked emails
• Status, IP addresses, geolocation
• Interaction timestamps (send, open, click)
• Aggregate statistics

Example:

{
  "campaign_id": 123
}

3. gophish_campaign_summary

Get summary statistics and calculated rates for a campaign.

Parameters:

• campaign_id (required): Campaign ID (positive integer)

Returns:

• Campaign metadata
• Raw statistics
• Calculated rates (open rate, click rate, submit rate, report rate)
• Dates (created, launched, completed)

Example:

{
  "campaign_id": 123
}

4. gophish_group_list

List target groups without exposing individual email addresses.

Parameters:

• limit (optional): Maximum number of results (1-100, default 25)

Returns:

• Group metadata (id, name, modified date)
• Number of targets (count only, no emails)

Example:

{
  "limit": 25
}

5. gophish_template_list

List email templates used in campaigns.

Parameters:

• limit (optional): Maximum number of results (1-100, default 25)

Returns:

• Template metadata (id, name, subject)
• Attachment information (presence and count)
• Modification date

Example:

{
  "limit": 25
}

6. gophish_landing_page_list

List landing pages used in campaigns.

Parameters:

• limit (optional): Maximum number of results (1-100, default 25)

Returns:

• Landing page metadata (id, name)
• Credential capture settings
• Redirect URL
• Modification date

Example:

{
  "limit": 25
}

7. gophish_campaign_timeline

Get chronological timeline of events for a campaign.

Parameters:

• campaign_id (required): Campaign ID (positive integer)

Returns:

• Timeline of events with masked emails
• Event types (email sent, opened, clicked, etc.)
• Event statistics by type
• Timestamps

Example:

{
  "campaign_id": 123
}

Email Masking

Email addresses are automatically masked using the following algorithm:

• Local part (before @): First character + "***" + last character

  • john.doe → j***e
  • admin → a***n

• Domain part (after @): First character + "***" + TLD

  • example.com → e***.com
  • corporate.internal.net → c***.net

Full example: [email protected] → j***e@e***.com

Security Features

1. HTTPS Enforcement: API URL must use HTTPS or be localhost
2. Read-Only: Only GET requests allowed (enforced in code)
3. Email Masking: All email addresses automatically masked
4. No Target Lists: Group listings don't expose individual emails
5. API Key Protection: Passed securely in Authorization header

Error Handling

The server provides detailed error messages for:

• Missing environment variables
• Invalid HTTPS/localhost configuration
• Invalid campaign IDs (must be positive integers)
• GoPhish API errors (with status codes)
• Network/connection issues

Use Cases

• Security Awareness Training: Analyze campaign effectiveness
• Reporting: Generate phishing simulation reports
• Metrics Tracking: Monitor open rates, click rates, report rates
• Compliance: Document security training activities
• Research: Analyze phishing behavior patterns (anonymized)

Limitations

• Read-Only: Cannot create, modify, or delete campaigns
• No Email Export: Individual email addresses are always masked
• Rate Limiting: Subject to GoPhish API rate limits
• Results Limit: Maximum 100 results per query

GoPhish API Reference

This server uses the following GoPhish API endpoints (all GET requests):

• GET /api/campaigns/ - List campaigns
• GET /api/campaigns/:id - Get campaign details
• GET /api/campaigns/:id/results - Get campaign results
• GET /api/groups/ - List target groups
• GET /api/templates/ - List email templates
• GET /api/pages/ - List landing pages

For more information, see the GoPhish API Documentation.

Development

# Install dependencies
bun install

# Build
bun run build

# Run in development
bun run start

TypeScript Configuration

The project uses ES2022 with bundler module resolution for Bun compatibility. See tsconfig.json for details.

License

This MCP server is independent of GoPhish. Please refer to GoPhish's license for the platform itself.

Support

For issues related to:

• This MCP server: Open an issue in this repository
• GoPhish platform: See GoPhish documentation
• MCP protocol: See Model Context Protocol documentation

Privacy Notice

This server is designed with privacy in mind:

• Email addresses are automatically masked
• No personally identifiable information is exposed in clear text
• Target group listings only show counts, not individual emails
• All data access is read-only

Use responsibly and in accordance with your organization's privacy policies.