npm package: @modular-intelligence/gophish
Description: MCP server for GoPhish phishing simulation platform API (read-only)
Latest version: 1.0.2

# GoPhish MCP Server

A Model Context Protocol (MCP) server for the [GoPhish](https://getgophish.com/) 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

```bash
cd gophish
bun install
```

## Configuration

Set the following environment variables:

```bash
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

```bash
# 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):

```json
{
  "mcpServers": {
    "gophish": {
      "command": "bun",
      "args": ["run", "/path/to/mi-mcp-servers/packages/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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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**: `john.doe@example.com` → `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](https://docs.getgophish.com/api-documentation/).

## Development

```bash
# 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](https://docs.getgophish.com/)
- **MCP protocol**: See [Model Context Protocol documentation](https://modelcontextprotocol.io/)

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